开发工具 Actions 矩阵传递工件 怎样处理

两个矩阵任务都生成 report.txt，却把工件都叫 reports，常见结果不是“自动汇总”，而是上传名称冲突。GitHub Actions 矩阵传递工件要拆开两层命名：上传名带矩阵维度，下游先按工件名保留目录，再读取里面的文件。本文用 zh、en 两路报告演示，不做发布或部署。

矩阵工件名负责区分产出者，下载目录负责隔离内容。让多个任务向同名工件追加，或直接把同名文件合到一个目录，都不是可靠的汇总办法。

官方入口：https://github.com/actions/upload-artifact。下载动作说明：https://github.com/actions/download-artifact。示例面向 GitHub.com 的独立练习仓库和 GitHub 托管 Ubuntu 运行器，使用当前官方 README 展示的 upload-artifact@v7 与 download-artifact@v8；不据此推断 GitHub Enterprise Server 或旧自托管运行器兼容性。图中界面是原创操作示意，以下输出是预期状态，未在本机运行。

1. 在仓库建立手动运行的工作流

在练习仓库进入 Code → Add file → Create new file，文件名输入 .github/workflows/matrix-artifacts.yml。已有工作流先另建文件，不覆盖真实项目的构建和部署流程。仓库需允许 Actions，并且你的账户具备写权限；没有权限时请管理员按组织规则处理，不要直接扩大令牌权限。

场景设定很小：produce 按 language 生成 zh、en 两份文本，两边都叫 report.txt；collect 必须分别找到两份文件。它们不是一个共享工作目录，文件跨 job 需要显式传递。整个例子不读取仓库源码，因此没有 checkout 步骤，也不需要自建密钥。

先保持文件编辑页打开，下一步写入完整工作流。此时只有路径和编辑入口准备好，尚未提交或执行。

2. 按矩阵值上传并在汇总任务下载

将下面完整配置放入编辑器。重点看 upload 的 name、collect 的 needs，以及 download 的 pattern 和 merge-multiple。两个 report.txt 内容不同，但无需为了避免碰撞随意改业务文件名。

name: Matrix artifact lab
on:
  workflow_dispatch:

# 示例不读取源码、不访问发布接口，关闭默认令牌权限。
permissions: {}

jobs:
  produce:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        language: [zh, en]
    steps:
      - name: Make report
        shell: bash
        env:
          REPORT_LANGUAGE: ${{ matrix.language }}
        run: |
          # 每个job有自己的目录，只生成无敏感信息的文本。
          mkdir -p out
          printf 'language=%s\n' "$REPORT_LANGUAGE" > out/report.txt

      - name: Upload report
        uses: actions/upload-artifact@v7
        with:
          # 唯一名称包含所有能区分本例矩阵产物的维度。
          name: report-${{ matrix.language }}
          path: out/report.txt
          if-no-files-found: error
          retention-days: 3

  collect:
    runs-on: ubuntu-latest
    # 等待produce的矩阵任务，默认失败时不进入汇总。
    needs: produce
    steps:
      - name: Download reports
        uses: actions/download-artifact@v8
        with:
          pattern: report-*
          path: incoming
          # 两份工件都含report.txt，保持独立目录。
          merge-multiple: false

      - name: Check reports
        shell: bash
        run: |
          # 精确检查两个预期文件，不能只依赖下载步骤显示成功。
          test -f incoming/report-zh/report.txt
          test -f incoming/report-en/report.txt
          grep -Fx 'language=zh' incoming/report-zh/report.txt
          grep -Fx 'language=en' incoming/report-en/report.txt

点 Commit changes，在提交对话框写清“新增矩阵工件练习”，提交到练习仓库默认分支；真实团队仓库应遵循分支审查流程。完成后 Code 文件列表应存在这份 YAML。workflow_dispatch 的工作流要在默认分支存在，才可按后文入口手动触发。

接着进入 Actions → Matrix artifact lab → Run workflow，在 Branch 中选练习默认分支，再点 Run workflow。这一步会实际消耗 Actions 运行资源；只需触发一次，等待新运行出现，不要因为页面暂未刷新连续点击。

这份配置刻意保留了目录隔离：工件名是 report-zh 和 report-en，文件名仍都是 report.txt。若再增加操作系统、架构等维度，name 也要覆盖新增的区分维度。overwrite 不是矩阵“追加”开关；用覆盖抢同一个名称会丢失先前对象，不应拿它修复并发命名设计。

这里的 permissions: {} 不额外授予 GITHUB_TOKEN 的仓库权限，示例没有跨运行下载。工件动作在当前 job 中使用运行环境提供的工件服务凭据；不要因为看到权限字段为空，就向 YAML 填个人访问令牌。

3. 从运行摘要定位工件与异常

进入 Actions → Matrix artifact lab → 本次运行，先看 produce 的两项矩阵 job，再点 collect → Check reports。示例全部成功时，日志应包含 language=zh 和 language=en。两项检查缺一不可：下载动作完成，只能说明它结束了，不能替代项目对产物完整性的判断。

回到这次运行的 Summary，在 Artifacts 区域应能分别找到 report-zh、report-en。登录且具备仓库读取权限的用户，可点击工件名下载，检查各自的 report.txt；不要误进另一次运行的摘要。collect 中下载的文件不会自动变成第三份服务器工件，想保存汇总结果需要另加一次独立上传。

以下是这份配置的预期下载布局，不是实际执行日志：

incoming/
  report-zh/
    report.txt
  report-en/
    report.txt

若上传失败，先打开对应 produce → Upload report，看是同名冲突还是 path 没匹配到文件。if-no-files-found: error 能让缺文件的上传直接失败，避免只出现警告后误以为已产出报告。若 collect 被跳过，先看上游是否失败，不要直接加 always() 绕过依赖语义。

若汇总找不到文件，按“本次运行 → 工件名称 → 下载 pattern → 实际目录”逐项比对。不要把浏览器下载的 ZIP 文件名，当作下载动作解包后的路径。本例不使用 merge-multiple: true，因为两个工件内部具有相同相对路径；合并不等于内容拼接。

能不能让每一路只下载自己的工件？

可以，把下游也设成相同矩阵，按完整 name 定向下载。例如 zh 消费者只取 report-zh；只有确实需要整体比较时才用单一 collect 汇总。先明确“逐路消费”还是“全部汇总”，再选 name 或 pattern，不用模糊通配符掩盖产物归属。

重跑、跨运行和过期工件怎么办？

本例讲同一次工作流运行内的交接。重新执行时要考虑命名和运行尝试的区分；跨运行下载需要显式定位目标运行并按官方动作要求配置访问权限，不能默认取到上次的工件。retention-days 也受仓库策略约束，过期或已删除的工件不是改下载目录能恢复的。

如何回退而不影响已有流水线？

取消仍在运行的练习任务，按仓库流程回退新增工作流文件即可，不修改其他工作流的权限和触发条件。不要上传 .env、凭据、整份主目录或未知缓存；本例仅上传 out/report.txt。真正交付时，应在团队审核后将动作版本固定到认可的提交 SHA，而不是把示例标签视作永远不变的版本。

参考：官方上传动作与矩阵命名说明、官方下载动作与目录规则、手动运行入口、运行摘要下载入口。