GitHub Actions matrix.include 怎样表达差异参数

当一份 GitHub Actions 工作流要覆盖多个操作系统和 Node.js 版本时，基础矩阵能减少重复配置；但某一个组合往往还需要额外参数，例如 Windows + Node 20 要固定 npm 6。此时可以用 matrix.include 表达差异，不必复制整个 job。

本文用一个最小的 Node.js 测试任务说明三件事：怎样给已存在的组合追加字段，什么时候会创建新组合，以及怎样在运行摘要里核对最终参数。

官方地址：https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations

include 中的对象如果不覆盖基础矩阵已有值，就会把新增键附加到匹配组合；如果无法安全加入任何组合，就会生成一个新的矩阵组合。

先准备一份基础矩阵

先把真正需要形成笛卡尔积的维度写进 matrix。下面的配置会产生 Ubuntu/Windows 与 Node 18/20 的四个基础 job。示例中的中文注释只说明字段职责，实际文件仍然是合法 YAML。

name: matrix-include-demo

on:
  push:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      # 中文注释：基础维度会组合成 2 x 2 个 job
      matrix:
        os: [ubuntu-latest, windows-latest]
        node-version: [18, 20]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          # 中文注释：每个 job 从当前矩阵读取自己的 Node 版本
          node-version: ${{ matrix.node-version }}
      - run: npm test

这里的 matrix.os 决定 runner，matrix.node-version 决定 setup-node 的版本。不要把只对一个组合生效的参数先塞进公共 steps，否则后面还要额外写很多条件判断。

用 include 给单个组合追加参数

如果只有 Windows + Node 20 需要 npm 6，可以在同一个 matrix 下添加 include。它不是重新定义一份矩阵，而是尝试把对象中的键值放进已有组合。

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node-version: [18, 20]
    include:
      # 中文注释：这两个值都匹配基础组合，因此只追加 npm-version
      - os: windows-latest
        node-version: 20
        npm-version: 6
        experimental: false
  fail-fast: false

steps:
  - uses: actions/setup-node@v4
    with:
      # 中文注释：只有 include 提供该字段时，才执行额外的 npm 版本设置
      node-version: ${{ matrix.node-version }}
  - if: ${{ matrix.npm-version }}
    run: npm install --global npm@${{ matrix.npm-version }}
  - run: npm test

这个对象不会把 os 或 node-version 改成别的值：它们与已有组合相同，所以 npm-version 和 experimental 会作为额外属性附加到 Windows + Node 20。没有附加字段的 job 中，表达式结果为空，条件步骤会被跳过。

哪些 include 会变成新的组合

判断一个对象是“追加字段”还是“新增 job”，关键看它是否能在不覆盖原矩阵值的前提下加入某个基础组合。可以用下面的表快速判断：

因此，include 适合表达少量例外，不适合代替完整的矩阵维度设计。如果新增 job 本身还需要不同的 runner、权限或步骤，最好把差异字段写清楚，并在步骤里通过 if 使用它。

在运行摘要里核对最终组合

提交工作流后，打开对应的 Actions 运行记录，先看矩阵 job 列表，再点进具体 job 查看变量和步骤。核对时不要只数 job 数量，重点看差异参数是否落在预期组合。

1. 在运行摘要中按 job 名称区分操作系统和 Node 版本。
2. 打开 Windows + Node 20 的 job，确认 npm-version 显示为 6。
3. 查看该 job 是否执行了全局 npm 设置步骤；Ubuntu job 不应因空值进入这个步骤。
4. 如果写了无法匹配基础矩阵的 include，对照 job 总数确认它是否作为新增组合出现。

和 exclude、对象数组怎么配合

exclude 用来移除不需要的基础组合，而 include 在矩阵处理后补充或扩展配置；如果业务规则是“所有 Windows 任务都带一个环境字段”，可以考虑直接使用对象数组，让一个维度的每个元素携带自己的属性。

matrix:
  os:
    - name: ubuntu-latest
      shell: bash
    - name: windows-latest
      shell: pwsh
  node-version: [18, 20]

steps:
  - run: npm test
    shell: ${{ matrix.os.shell }}
    # 中文注释：对象数组适合描述每个平台固有的附加属性

速记原则是：基础维度决定组合范围，include 处理少数差异，exclude 处理明确不要的组合，对象数组处理某个维度自身带有稳定属性的情况。三者混在一起时，优先让字段名表达业务含义，再从运行摘要回看实际 job。

相关问题

include 能覆盖基础矩阵中的值吗？

它不会直接改写原矩阵值。若对象中的键值与某个基础组合冲突，不能安全加入该组合时，GitHub Actions 可能把对象作为新的组合处理。

include 只写一个新字段会发生什么？

如果这个字段能附加到已有组合，相关组合会获得它；如果无法与任何组合安全合并，则会产生一个带该字段的新组合。实际 job 数量和变量值应以运行摘要为准。

什么时候不该继续增加 include？

当例外条目已经多到难以从 YAML 看出矩阵范围时，说明基础维度或 job 拆分需要重新设计。此时把稳定属性放入对象数组，或拆出独立 job，通常比继续堆 include 更容易维护。