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,通常可以并行执行。

配置版本矩阵
下面的工作流在推送和 Pull Request 时测试三个 Node.js 版本。${{ matrix.node-version }} 会在每个矩阵实例中替换为当前组合的值。
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 运行结果中看到三个矩阵实例成功;实际显示名称和耗时可能略有不同。
test (20) success
test (22) success
test (24) success理解组合数量
矩阵可以同时声明多个维度。例如运行版本有 3 个值、操作系统有 2 个值时,默认会生成 个组合。组合数量增长很快,因此不要为了“覆盖更多”随意加入没有兼容性意义的维度。
片段示例:下面只展示 strategy 和 runs-on 部分,需要放入完整 Job 中使用。
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 更容易判断问题是否与运行版本相关。
test (20) success
test (22) success
test (24) failure预期结果:在 fail-fast: false 下,一个版本失败不会仅因为矩阵快速失败策略而取消其他版本;整个工作流仍会因为存在失败的测试实例而不能视为全部通过。
矩阵最适合表达“测试步骤相同、环境变量不同”的场景。只有真正需要支持的运行版本或操作系统才应进入矩阵;这样既能持续验证兼容性,也不会让组合数量和 CI 时间无意义地膨胀。