开源项目的CI测试矩阵如何配置

本文目录导读：

1. GitHub Actions 配置（最常用）
2. GitLab CI 配置
3. 关键设计原则
4. 典型矩阵推荐（根据语言）
5. 实用技巧
6. 最终检查清单

开源项目的CI测试矩阵配置通常需要覆盖多版本、多操作系统、多依赖组合以及不同硬件架构，具体配置方式取决于你使用的 CI 平台（GitHub Actions、GitLab CI、Jenkins 等）。

以下以最流行的 GitHub Actions 和 GitLab CI 为例，给出典型的测试矩阵配置方法。

GitHub Actions 配置（最常用）

GitHub Actions 通过 strategy.matrix 来实现矩阵构建，以下是一个针对 Python 项目的完整示例：

基础矩阵：多版本 + 多操作系统

name: CI
on:
  push:
    branches: [ main, dev ]
  pull_request:
    branches: [ main ]
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]   # 操作系统矩阵
        python-version: ['3.9', '3.10', '3.11', '3.12']    # 版本矩阵
        include:                                            # 额外添加特定组合（可选）
          - os: ubuntu-latest
            python-version: '3.8'                           # 额外测试旧版
        exclude:                                            # 排除已知不兼容组合（可选）
          - os: windows-latest
            python-version: '3.8'
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest
      - name: Run tests
        run: pytest

依赖组合矩阵（例如不同数据库版本、不同库版本）

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        # 版本与数据库两个维度组合
        python-version: ['3.10', '3.11']
        database: ['postgres:13', 'postgres:14', 'mysql:8.0']
    services:
      # 根据矩阵动态启动数据库容器
      db:
        image: ${{ matrix.database }}
        env:
          POSTGRES_PASSWORD: testpass
          MYSQL_ROOT_PASSWORD: testpass
        ports:
          - 5432:5432
          - 3306:3306

并行限制与失败处理

strategy:
  fail-fast: false      # 某个 Job 失败时，不要停止其他 Job（推荐用于开源项目）
  max-parallel: 8       # 同时最多运行 8 个 Job（防止免费额度超限）
  matrix:
    node-version: [14, 16, 18, 20]

GitLab CI 配置

GitLab CI 使用 parallel 和 matrix 关键字（需要 GitLab 13.3+）。

使用 parallel:matrix

stages:
  - test
test:
  stage: test
  image: python:${PYTHON_VERSION}
  parallel:
    matrix:
      - PYTHON_VERSION: ['3.9', '3.10', '3.11']
        OS: ['ubuntu', 'windows']   # 注意：Windows Runner 需要单独配置 tag
  script:
    - pip install -r requirements.txt
    - pytest
  tags:
    - $OS                    # 根据矩阵变量动态选择 Runner

使用 extends 实现更复杂的矩阵

.test-template:
  stage: test
  script: pytest
test-python3.9:
  extends: .test-template
  image: python:3.9
test-python3.10:
  extends: .test-template
  image: python:3.10
test-python3.11:
  extends: .test-template
  image: python:3.11

关键设计原则

典型矩阵推荐（根据语言）

实用技巧

1. 使用环境变量传递矩阵信息
   在 env 中引用 ${{ matrix.os }} 或 ${{ matrix.version }}，方便日志输出和分支处理。

2. 缓存依赖以加速
   GitHub Actions 示例：

   - uses: actions/cache@v4
     with:
       path: ~/.cache/pip
       key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}

3. 标记矩阵 Job 名称
   使用 name 字段让日志更清晰：

   name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})

4. 条件跳过某些 Job

   if: matrix.os != 'windows-latest'  # 跳过 Windows 上的某些耗时测试

最终检查清单

• [ ] 是否覆盖了你的目标用户的主流操作系统和版本？
• [ ] 是否包含了 fail-fast: false？
• [ ] 是否使用了 include/exclude 精准控制组合？
• [ ] 是否设置了合理的 max-parallel（建议 5~10）？
• [ ] 是否有快速检查 Job（仅最新版本 + 最常用 OS）用于快速反馈？

如果你给一下具体语言/框架，我可以帮你生成可直接粘贴的 YAML 配置。