CI/CD / 系统课时

用矩阵测试多个运行版本

用矩阵测试多个运行版本

项目往往不能只保证在一个运行版本上工作。本节使用 GitHub Actions 的 matrix strategy,把同一个测试 Job 展开成多个并行任务,让不同 Node.js 版本分别安装依赖和运行测试,并能从结果中快速发现版本兼容性问题。

学习目标

  • 理解 matrix 如何把一个 Job 展开为多个运行实例
  • 配置多个 Node.js 版本的并行测试
  • 使用 fail-fast 和矩阵结果判断兼容性问题

矩阵解决什么问题

假设一个库声明同时支持 Node.js 20、22 和 24,只在开发机的 Node.js 22 上测试并不能证明另外两个版本可用。复制三个几乎相同的 Job 虽然可行,却会造成配置重复,版本增加时也更难维护。

矩阵把变化的维度抽成数据。GitHub Actions 会计算配置中的组合,并为每个组合创建独立 Job。三个 Node.js 版本对应三个测试实例,它们拥有独立 Runner,通常可以并行执行。

GitHub Actions矩阵展开多个测试任务

配置版本矩阵

下面的工作流在推送和 Pull Request 时测试三个 Node.js 版本。${{ matrix.node-version }} 会在每个矩阵实例中替换为当前组合的值。

yaml
name: Matrix Test

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node-version: [20, 22, 24]

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

这是完整配置示例,前提是项目包含 package.json、匹配的 package-lock.json 和可执行的 test 脚本。矩阵只有一个维度,因此一共产生 3 个 Job 实例,而不是在同一个 Runner 中依次切换三个版本。

预期结果:测试全部兼容时,可以在 Actions 运行结果中看到三个矩阵实例成功;实际显示名称和耗时可能略有不同。

text
test (20)  success
test (22)  success
test (24)  success

理解组合数量

矩阵可以同时声明多个维度。例如运行版本有 3 个值、操作系统有 2 个值时,默认会生成 3×2=63 \times 2 = 6 个组合。组合数量增长很快,因此不要为了“覆盖更多”随意加入没有兼容性意义的维度。

片段示例:下面只展示 strategy 和 runs-on 部分,需要放入完整 Job 中使用。

yaml
strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-latest, windows-latest]
    node-version: [20, 22, 24]

runs-on: ${{ matrix.os }}

生效行为:GitHub Actions 会展开 2 个操作系统与 3 个 Node.js 版本的笛卡尔积,共创建 6 个 Job 实例。验证时可在一次工作流运行中检查六种组合是否都出现。

控制失败时的执行方式

fail-fast 控制矩阵中某个非实验性 Job 失败后,是否取消仍在排队或运行的其他矩阵 Job。默认值为 true。兼容性测试通常更关心“哪些版本失败”,因此设置为 false 可以尽量收集完整结果,而不是在第一个失败后停止其他组合。

如果 Node.js 20 成功、22 成功而 24 失败,先查看 24 对应实例中的第一个失败步骤。因为每个实例使用相同测试逻辑,差异集中在矩阵变量上,这比三个手写 Job 更容易判断问题是否与运行版本相关。

text
test (20)  success
test (22)  success
test (24)  failure

预期结果:在 fail-fast: false 下,一个版本失败不会仅因为矩阵快速失败策略而取消其他版本;整个工作流仍会因为存在失败的测试实例而不能视为全部通过。

矩阵最适合表达“测试步骤相同、环境变量不同”的场景。只有真正需要支持的运行版本或操作系统才应进入矩阵;这样既能持续验证兼容性,也不会让组合数量和 CI 时间无意义地膨胀。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用矩阵测试多个运行版本

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通