首页/开发/CI/CD 与发布速查/矩阵构建(Matrix)
流水线设计54 条

矩阵构建(Matrix)

一个定义展开成多组参数组合(多版本、多平台、多配置),天然并行,适合跨语言版本与跨操作系统验证。

CI/CD 与发布速查开发更新于 2026-10-13

矩阵构建是什么

一个作业定义展开成多组参数组合:语言版本、操作系统、依赖版本各自成维度,组合数量等于各维度取值相乘。矩阵天然并行执行,适合验证跨版本兼容性与跨平台行为;代价是作业数量与费用随维度成倍增长,需要用 include 与 exclude 精确控制规模,而不是每维都拉满。

基本信息

GitHubstrategy.matrix 配 include/exclude,fail-fast 可关闭
GitLabparallel:matrix 基于变量组合展开作业
Jenkins声明式 pipeline 的 matrix 指令
命名识别GitHub 用矩阵变量拼作业名,失败时一眼看出组合
组合数各维度取值相乘,三个维度各五档就是十五个作业

典型使用场景

  • 跨语言版本:多个运行时版本同时验证兼容性。
  • 跨操作系统:Linux 与 Windows 各自打包与验证。
  • 跨数据库:多引擎或多版本跑同一套集成测试。
  • 发布产物:每个平台组合产出一份安装包。
  • 回归抽样:按风险挑选代表组合而非全量笛卡尔积。
  • 依赖组合:锁文件与运行时版本交叉覆盖。

GitHub matrix

GitHub matrix
jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [20, 22]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with: {node-version: '${{ matrix.node }}'}

规模控制手段

手段作用说明
exclude去掉不可能的组合旧版本加新系统这类无效搭配
include追加特殊组合补一个带额外变量的特例
fail-fast: false失败不取消其余组合用于收集完整矩阵结果
代表性取值控制总量只保留各维度关键档位
组合数等于各维度取值相乘:用 exclude 去掉不可能组合,先控总规模再谈覆盖率。
矩阵作业通过矩阵变量读取当前组合值;新增一个维度往往把耗时与费用成倍放大,先评估再扩。
高阶运行器计费更贵:跨平台矩阵按必需程度选档位,常见的 Linux 组合加密,稀有平台降频跑。

易错点

  • 矩阵规模失控:3 个维度各 5 个取值就是 125 个作业,按风险挑选代表组合。
  • fail-fast 默认开启:一个组合失败会取消其余组合,需要完整报告时显式关闭。
  • exclude 规则漏配:无效组合浪费算力,且常年一片红。
  • 矩阵内重复全流程:每个组合都跑一遍发布路径,应只验证必要环节。
  • 把矩阵当性能测试:资源争抢互相干扰,压测应独立调度。
  • 组合命名不含变量:失败列表分不清是哪个平台哪个版本出的问题。

数据来源与参考

  • GitHub Docs《Using a matrix for your jobs》
  • GitLab Docs《Parallel: matrix》
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌