GitHub Actions 怎样用矩阵并行多个运行组合

如果一组测试只是在操作系统或运行时版本上变化，不需要复制多个几乎相同的 job。GitHub Actions 的 strategy.matrix 可以把一份任务定义展开成多个组合，再用 matrix. 把当前组合传给 runs-on、动作参数和脚本。二维矩阵会产生变量值的笛卡尔积；max-parallel 只限制同时运行的数量，不会减少组合总数。

官方地址：https://github.com/

对应文档：https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations

第1步：找到工作流任务并确定矩阵变量

先打开仓库中 .github/workflows 目录下的 YAML 文件，找到要重复执行的 job。例如同一套测试需要覆盖两个系统和三个 Go 版本，那么变化因素就是 os 与 go。固定的检出、安装依赖和测试命令仍然保留在同一个 job 里。

变量要表达“这次运行为什么不同”。如果只是某一个组合需要额外参数，不要先复制整个 job，后面可以用 include 给它补字段；如果某个组合永远不该运行，再用 exclude 剔除。

第2步：在 job 下写入 strategy.matrix

在目标 job 下添加 strategy.matrix，并把矩阵变量接到运行环境和安装动作中。下面的示例把两个系统与两个版本组合成四个独立的 job 运行：

name: matrix-test

on:
  push:

jobs:
  test:
    # 用一份任务定义覆盖多套测试环境。
    runs-on: ${{ matrix.os }}
    strategy:
      # 两个 os 乘两个 go，最终会展开为四个组合。
      matrix:
        os: [ubuntu-latest, windows-latest]
        go: ['1.23', '1.24']
    steps:
      - name: Checkout
        # 拉取当前提交，保证每个矩阵任务使用同一份代码。
        uses: actions/checkout@v4
      - name: Set up Go
        # 将当前组合的 Go 版本传给官方安装动作。
        uses: actions/setup-go@v5
        with:
          go-version: ${{ matrix.go }}
      - name: Test
        # 每个组合都执行相同测试命令，失败状态会回传给矩阵任务。
        run: go test ./...

这里的 matrix.os 和 matrix.go 是 GitHub Actions 表达式，不是脚本运行后才创建的环境变量。组合任务启动前，Actions 会为每个组合计算表达式，再把对应值交给 runs-on 和 setup-go。

第3步：用 include 和 exclude 修正组合

默认情况下，矩阵变量会做全组合。如果某个系统和版本组合没有测试价值，可以用 exclude 删除；如果某个组合要增加额外的环境变量或测试开关，可以用 include 添加属性：

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    go: ['1.23', '1.24', '1.25']
    # 排除已知不需要运行的组合，避免无效消耗。
    exclude:
      - os: windows-latest
        go: '1.23'
    # 只给 Linux 的最新版本附加一个矩阵字段。
    include:
      - os: ubuntu-latest
        go: '1.25'
        race: true

steps:
  - name: Test
    # 布尔字段也通过表达式传入脚本，默认值由脚本自行处理。
    run: go test ./...

exclude 要写出要删除的变量组合；include 则可以为已有组合增加字段，也可能创建一条新的组合。修改后不要只看数组行数，应按实际展开的组合核对结果。

第4步：调整失败策略和并发上限

当矩阵中有一个任务失败时，是否取消其它进行中的任务，由 fail-fast 决定。默认行为适合“首个失败就尽快结束”的快速反馈；如果每个系统的失败结果都需要保留，可以关闭它：

strategy:
  # 让其它组合继续完成，便于一次收集全部平台结果。
  fail-fast: false
  matrix:
    os: [ubuntu-latest, windows-latest]
    go: ['1.23', '1.24', '1.25']
  # 同时最多运行两个矩阵任务，降低并发资源压力。
  max-parallel: 2

max-parallel: 2 不会把六个组合变成两个组合，而是让它们分批进入运行状态。资源紧张、并发受限或需要控制外部服务压力时可以设小一些；希望更快完成且配额允许时再提高。

第5步：从运行结果核对组合数量

保存工作流并触发一次运行后，打开对应的 workflow run，展开 test job。示例中的两个系统乘三个 Go 版本应出现六个组合；若使用了 exclude，数量还要减去被排除的组合。检查每个任务名称中的系统和版本，避免因为表达式拼写错误而得到错误的运行环境。

如果页面同时出现 queued、running 和 success，不要把 queued 误判为未展开。结合 max-parallel 判断：六个组合仍然存在，只是同一时刻最多有两个进入运行中。任务完成后，至少核对失败组合的日志、运行器系统和实际版本。

常见问题：为什么矩阵运行数量和预期不同

两个变量会产生多少个任务？

先计算变量值的组合数。例如两个 os 值乘三个 go 值，默认是六个任务；再扣除 exclude 删除的组合，并把 include 新增或扩展的组合算进去。

max-parallel 会减少计费任务数量吗？

不会。它只限制同时运行的矩阵任务数量，所有没有被排除的组合仍然会排队并最终运行。

为什么 runs-on: ${{ matrix.os }} 没有按系统切换？

检查表达式是否写在 job 的 YAML 字段中，并确认矩阵变量名与 matrix 下的键完全一致。不要在 run 脚本中把它误写成 $matrix.os；表达式和 shell 变量是两套语法。

什么时候应该关闭 fail-fast？

当你需要保留所有平台和版本的测试结果、或者失败原因可能只与某个平台有关时，可以设置 false。如果只关心最快发现任一回归，默认的快速取消更省资源。

最后按这四项验收：矩阵变量确实代表不同测试环境；matrix 表达式已经接到运行器和动作参数；include/exclude 没有改变预期边界；运行结果中的组合数量与 max-parallel 的含义一致。