GitHub Actions 怎样用矩阵生成多版本测试任务

如果同一套测试要覆盖多个运行时版本或操作系统，不必复制出一组组几乎相同的 job。GitHub Actions 的 strategy.matrix 可以把一个 job 定义展开成多组组合任务：例如 3 个 Node.js 版本乘以 2 个 runner，就得到 6 个测试任务。配置完成后，再到工作流运行页按版本和系统核对每一组状态。

官方地址：https://docs.github.com/actions/using-jobs/using-a-matrix-for-your-jobs

先把矩阵任务拆成可数的组合

进入仓库的 .github/workflows 目录，新建或打开测试工作流文件。在编辑器中找到目标 job 的 strategy 区域，添加 matrix。软件教程里的路径可以概括为：仓库 → Actions → 工作流文件 → job → Strategy/Matrix。这里先只做两件事：列出要测试的版本，再列出要使用的 runner。

下面的配置用三个 Node.js 版本和两个系统组成 6 个组合。matrix.node、matrix.os 是后续步骤读取当前组合值的入口：

name: matrix test

on:
  push:
  pull_request:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        # 这里声明要覆盖的运行时版本。
        node: [18, 20, 22]
        # 这里声明每个版本要运行的系统。
        os: [ubuntu-latest, windows-latest]
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          # 当前矩阵组合会把 node 值传给 setup-node。
          node-version: ${{ matrix.node }}
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

保存文件后，先在界面上数一遍组合：3 个 node 值 × 2 个 os 值 = 6。可见状态应是工作流文件已保存，矩阵摘要显示 6 个组合；如果只显示 3 个或 2 个，通常是某一维没有写成数组，或者 job 没有引用同一个 matrix。

把矩阵值接到运行环境和测试命令

回到 job 的步骤区域，打开 runs-on 和 setup action 的配置，确认它们读取的是 ${{ matrix.os }} 与 ${{ matrix.node }}，而不是写死某个版本。这样每个展开后的任务都会获得自己的运行环境。

点击工作流文件右上角的保存或提交入口，回到 Actions 页面选择对应工作流。提交后，可见状态应先出现一个运行记录，记录下方展开出带有版本和系统后缀的多个 job 名称。工作流中的测试命令仍然只写一份，变化的是每次任务拿到的矩阵值。

用 include、exclude 和并发设置收窄特殊组合

如果某个版本只需要额外环境变量，可以在 include 中追加字段；如果某一对版本与系统组合不适用，则用 exclude 移除。操作位置仍然是同一个 job → Strategy/Matrix 面板，修改后先确认组合数量发生了预期变化。

strategy:
  # 某个实验版本失败不会取消稳定版本的任务。
  fail-fast: false
  # 控制同时运行的矩阵任务数量，避免占满 runner。
  max-parallel: 2
  matrix:
    node: [18, 20, 22]
    os: [ubuntu-latest, windows-latest]
    exclude:
      # 例：暂时不在 Windows 上运行 Node 18。
      - node: 18
        os: windows-latest
    include:
      # 例：给 Node 22 的任务增加测试标记。
      - node: 22
        os: ubuntu-latest
        test-mode: extended

fail-fast: false 适合希望看完所有组合结果的场景；max-parallel 是并发上限，不是矩阵总数。修改后，如果组合从 6 变成 5，先确认是 exclude 的结果，而不是漏写了版本。

从运行页确认每个矩阵任务

进入仓库的 Actions → 目标工作流 → 最新运行记录。先看运行摘要中的任务总数，再展开每一个 job，重点核对版本、操作系统和最终状态。需要定位失败时，先看失败 job 的矩阵后缀，再打开该 job 的测试步骤日志；不要只根据总览页的红色状态猜原因。

可见的完成状态应包含：任务总数与配置相符；每个版本和系统组合都有记录；失败时能点进具体 job；全部任务完成后，工作流总览给出明确的成功或失败结论。只要有一组失败，最终门禁通常仍应保持失败，除非工作流另有明确的容错设计。

常见问题

为什么写了两个版本却出现四个任务？

矩阵会组合每个维度的值。如果版本有 2 个值、系统也有 2 个值，默认就是 4 个组合。检查 matrix 下是否同时声明了两个数组。

include 会不会把原来的组合全部替换掉？

不会。它会尝试给能匹配的组合追加字段；不能在不覆盖原值的情况下匹配时，会作为额外组合加入。需要减少任务时，应明确使用 exclude。

怎样避免一个失败任务让其它版本不再运行？

在 job 的 strategy 中设置 fail-fast: false，让其它已排队或运行中的组合继续完成，便于一次看到完整的版本覆盖结果。