{"meta":{"title":"在工作流中运行作业变体","intro":"创建一个矩阵来定义每个作业的变体。","product":"GitHub Actions","breadcrumbs":[{"href":"/zh/actions","title":"GitHub Actions"},{"href":"/zh/actions/how-tos","title":"操作方法"},{"href":"/zh/actions/how-tos/write-workflows","title":"编写工作流"},{"href":"/zh/actions/how-tos/write-workflows/choose-what-workflows-do","title":"选择工作流执行的操作"},{"href":"/zh/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations","title":"运行作业变体"}],"documentType":"article"},"body":"# 在工作流中运行作业变体\n\n创建一个矩阵来定义每个作业的变体。\n\n## 关于矩阵策略\n\n使用矩阵策略，可以在单个作业定义中使用变量自动创建基于变量组合的多个作业运行。 例如，可以使用矩阵策略在某个语言的多个版本或多个操作系统上测试代码。\n\n## 向工作流程作业添加矩阵策略\n\n使用 `jobs.<job_id>.strategy.matrix` 定义不同作业配置的矩阵。 在矩阵中，定义一个或多个变量，后跟一个值数组。 例如，以下矩阵有一个称为 `version` 的变量，其值为 `[10, 12, 14]` ，以及一个称为 `os` 的变量，其值为 `[ubuntu-latest, windows-latest]`：\n\n```yaml\njobs:\n  example_matrix:\n    strategy:\n      matrix:\n        version: [10, 12, 14]\n        os: [ubuntu-latest, windows-latest]\n```\n\n将针对各变量的每个可能组合执行任务。 在此示例中，工作流将运行六个作业，其中一个作业用于每个 `os` 和 `version` 变量组合。\n\n上述矩阵将按以下顺序创建作业。\n\n* `{version: 10, os: ubuntu-latest}`\n* `{version: 10, os: windows-latest}`\n* `{version: 12, os: ubuntu-latest}`\n* `{version: 12, os: windows-latest}`\n* `{version: 14, os: ubuntu-latest}`\n* `{version: 14, os: windows-latest}`\n\n有关参考信息和示例，请参阅 [GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrix)。\n\n## 使用上下文创建矩阵\n\n若要使用有关工作流运行、变量、运行程序环境、作业和步骤的信息创建矩阵，请使用 `${{ <context> }}` 表达式语法访问上下文。 有关上下文的详细信息，请参阅“[上下文参考](/zh/actions/reference/workflows-and-actions/contexts)”。\n\n例如，以下工作流触发事件 `repository_dispatch`，并使用事件有效负载中的信息来生成矩阵。 使用如下所示的有效负载创建存储库调度事件时，矩阵 `version` 变量的值为 `[12, 14, 16]`。 有关 `repository_dispatch` 触发器的详细信息，请参阅“[触发工作流的事件](/zh/actions/reference/workflows-and-actions/events-that-trigger-workflows#repository_dispatch)”。\n\n```json\n{\n  \"event_type\": \"test\",\n  \"client_payload\": {\n    \"versions\": [12, 14, 16]\n  }\n}\n```\n\n```yaml\non:\n  repository_dispatch:\n    types:\n      - test\n\njobs:\n  example_matrix:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        version: ${{ github.event.client_payload.versions }}\n    steps:\n      - uses: actions/setup-node@v7\n        with:\n          node-version: ${{ matrix.version }}\n```\n\n## 扩展或添加矩阵配置\n\n若要扩展现有矩阵配置或添加新配置，请使用 `jobs.<job_id>.strategy.matrix.include`。\n`include` 值是一个对象列表。\n\n例如，考虑以下矩阵。\n\n```yaml\nstrategy:\n  matrix:\n    fruit: [apple, pear]\n    animal: [cat, dog]\n    include:\n      - color: green\n      - color: pink\n        animal: cat\n      - fruit: apple\n        shape: circle\n      - fruit: banana\n      - fruit: banana\n        animal: cat\n```\n\n这将生成具有以下矩阵组合的六个作业。\n\n* `{fruit: apple, animal: cat, color: pink, shape: circle}`\n* `{fruit: apple, animal: dog, color: green, shape: circle}`\n* `{fruit: pear, animal: cat, color: pink}`\n* `{fruit: pear, animal: dog, color: green}`\n* `{fruit: banana}`\n* `{fruit: banana, animal: cat}`\n\n每个 `include` 条目都按以下方式应用。\n\n* `{color: green}` 被添加到所有原始矩阵组合中，因为它可以添加，而不会覆盖原始组合的任何部分。\n* `{color: pink, animal: cat}` 仅将 `color:pink` 添加到包含 `animal: cat` 的原始矩阵组合中。 这会覆盖上一个 `color: green` 条目添加的 `include`。\n* `{fruit: apple, shape: circle}` 仅将 `shape: circle` 添加到包含 `fruit: apple` 的原始矩阵组合中。\n* `{fruit: banana}` 无法添加到任何原始矩阵组合而不覆盖值，因此作为额外的矩阵组合添加\n* `{fruit: banana, animal: cat}` 无法添加到任何原始矩阵组合而不覆盖值，因此作为额外的矩阵组合添加 它不会添加到 `{fruit: banana}` 矩阵组合中，因为该组合不是原始矩阵组合之一。\n\n有关参考和示例配置，请参阅 [GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrixinclude)。\n\n## 排除矩阵配置\n\n若要移除矩阵中定义的特定配置，请使用 `jobs.<job_id>.strategy.matrix.exclude`。\n\n例如，以下工作流将运行 9 个作业：共 12 个配置中的每个配置运行一个作业，减去与 `{os: macos-latest, version: 12, environment: production}` 匹配的一个排除作业，以及与 `{os: windows-latest, version: 16}` 匹配的两个排除作业。\n\n```yaml\nstrategy:\n  matrix:\n    os: [macos-latest, windows-latest]\n    version: [12, 14, 16]\n    environment: [staging, production]\n    exclude:\n      - os: macos-latest\n        version: 12\n        environment: production\n      - os: windows-latest\n        version: 16\nruns-on: ${{ matrix.os }}\n```\n\n有关参考信息，请参阅 [GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrixexclude)\n\n## 使用输出定义两个矩阵\n\n可使用一个作业的输出来定义多个作业的矩阵。\n\n例如，以下工作流演示了如何在一个作业中定义值的矩阵，在第二个作业中使用该矩阵生成项目，然后在第三个作业中使用这些项目。 每个工件都与矩阵中的一个值相关联。\n\n```yaml copy\nname: shared matrix\non:\n  push:\n  workflow_dispatch:\n\njobs:\n  define-matrix:\n    runs-on: ubuntu-latest\n\n    outputs:\n      colors: ${{ steps.colors.outputs.colors }}\n\n    steps:\n      - name: Define Colors\n        id: colors\n        run: |\n          echo 'colors=[\"red\", \"green\", \"blue\"]' >> \"$GITHUB_OUTPUT\"\n\n  produce-artifacts:\n    runs-on: ubuntu-latest\n    needs: define-matrix\n    strategy:\n      matrix:\n        color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}\n\n    steps:\n      - name: Define Color\n        env:\n          color: ${{ matrix.color }}\n        run: |\n          echo \"$color\" > color\n      - name: Produce Artifact\n        uses: actions/upload-artifact@v4\n        with:\n          name: ${{ matrix.color }}\n          path: color\n\n  consume-artifacts:\n    runs-on: ubuntu-latest\n    needs:\n    - define-matrix\n    - produce-artifacts\n    strategy:\n      matrix:\n        color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}\n\n    steps:\n    - name: Retrieve Artifact\n      uses: actions/download-artifact@v5\n      with:\n        name: ${{ matrix.color }}\n\n    - name: Report Color\n      run: |\n        cat color\n```\n\n## 处理故障\n\n若要控制作业失败的处理方式，请使用 `jobs.<job_id>.strategy.fail-fast` 和 `jobs.<job_id>.continue-on-error`。\n\n可以同时使用 `jobs.<job_id>.strategy.fail-fast` 和 `jobs.<job_id>.continue-on-error`。 例如，以下工作流将启动四个作业。 对于每个作业，`continue-on-error` 都由 `matrix.experimental` 的值确定。 如果带有 `continue-on-error: false` 的任何任务失败，所有正在进行或排队的任务都将被取消。 如果具有 `continue-on-error: true` 的作业失败，则其他作业将不会受到影响。\n\n```yaml\njobs:\n  test:\n    runs-on: ubuntu-latest\n    continue-on-error: ${{ matrix.experimental }}\n    strategy:\n      fail-fast: true\n      matrix:\n        version: [6, 7, 8]\n        experimental: [false]\n        include:\n          - version: 9\n            experimental: true\n```\n\n有关参考信息，请参阅 [`jobs.<job_id>.strategy.fail-fast`](/zh/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategyfail-fast) 和 [`jobs.<job_id>.continue-on-error`](/zh/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idcontinue-on-error)。\n\n## 定义最大并发作业数\n\n若要设置使用 `matrix` 作业策略时可以同时运行的最大作业数，请使用 `jobs.<job_id>.strategy.max-parallel`。\n\n例如，以下工作流中，每次最多可以同时运行两个作业，即使有执行器可用以同时运行全部六个作业。\n\n```yaml\njobs:\n  example_matrix:\n    strategy:\n      max-parallel: 2\n      matrix:\n        version: [10, 12, 14]\n        os: [ubuntu-latest, windows-latest]\n```\n\n有关参考信息，请参阅 [GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymax-parallel)。"}