GitHub Actions 跨 job 共享构建产物的配置方法

GitHub Actions 的不同 job 运行在相互隔离的环境里，前一个 job 生成的文件不会自动出现在后一个 job。解决办法是：先在构建 job 用 actions/upload-artifact 上传，再让后续 job 写 needs: build 等待完成，并用 actions/download-artifact 下载到明确目录。

官方地址：https://docs.github.com/en/actions/tutorials/store-and-share-data

下面用一个 Go 二进制文件举例，目标是让 build 生成 dist/app-linux-amd64，让 package 下载后继续打包。这里传递的是构建结果，不是依赖缓存。

步骤1：从仓库文件入口创建工作流

打开仓库的 Code > Add file > Create new file，在文件名输入框填写 .github/workflows/artifact-transfer.yml。先把两个 job 的职责写清：build 负责编译和上传，package 负责下载和消费。

把下面配置粘贴到文件中，再点击页面右上角的 Commit changes 保存。YAML 注释说明了每个关键路径，便于以后排错。

name: Build and package

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Build binary
        run: |
          # 创建输出目录，避免上传路径不存在
          mkdir -p dist
          # 关闭 CGO，生成后续 job 要消费的 Linux 文件
          CGO_ENABLED=0 go build -o dist/app-linux-amd64 ./cmd/app
      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          # name 是后续 download-artifact 的精确匹配键
          name: go-build
          path: dist/app-linux-amd64

  package:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          # 下载名必须与上传名一致
          name: go-build
          # 指定后续命令实际读取的目录
          path: dist
      - name: Package result
        run: |
          # 先检查文件是否真的落盘，再进行打包
          test -f dist/app-linux-amd64
          tar -czf app-linux-amd64.tar.gz -C dist app-linux-amd64

保存后，页面能看到两个 job，且 package 下方标有 needs: build。这说明依赖关系已经写入工作流，而不是只靠步骤排列顺序。

步骤2：在前置 job 上传唯一构件

回到工作流编辑器，定位 build > Upload build artifact。重点检查 name: go-build 和 path: dist/app-linux-amd64：前者是传递键，后者是实际文件。点击 Commit changes 后，进入仓库 Actions 页面，选择刚刚的工作流运行。

当 Build binary 和上传步骤显示绿色成功标记时，构建 job 才算完成。若提示没有匹配文件，先回看编译命令的输出目录，不要先修改下载 job。

步骤3：让后续 job 下载并消费构件

在同一个 YAML 中定位 package job。第一行必须是 needs: build，否则它可能与构建 job 并行启动；下载动作的 name 必须和上传动作完全相同，path 则决定后续脚本从哪里读取。

运行成功后，test -f dist/app-linux-amd64 不会输出错误，后面的 tar 命令会生成压缩包。若下载成功但文件找不到，优先检查是否把上传路径的目录层级误当成下载后的文件名。

步骤4：在 Actions 页面验证依赖和路径

打开仓库的 Actions > Build and package > 对应运行记录，先看 build 再看 package。在运行摘要的 Artifacts 区域应看到 go-build；进入 package 日志，应看到下载步骤完成并通过文件检查。

如果 package 没有启动，先查看 build 是否失败；如果构件名称不存在，检查两个动作的 name 是否有大小写或空格差异。

步骤5：处理常见边界

• artifact 与 cache 不同：artifact 保存构建输出并供后续 job 或运行记录使用；cache 更适合复用不常变化的依赖，不能把缓存命中当作构建成功。
• 必须显式等待：同一工作流的跨 job 传递通常需要 needs，它同时表达执行顺序和失败传播关系。
• 跨工作流是另一种任务：如果目标是其他运行或其他仓库的构件，需要额外提供 run identifier、repository 和具备相应权限的 token，不能直接套用上面的同运行配置。
• 构件名要稳定：矩阵构建时给每个 job 加上系统或版本后缀，避免多个 job 争用同一个 artifact 名称。

常见问题

为什么第二个 job 里看不到前一个 job 生成的文件？因为不同 job 的工作目录不是同一份文件系统。需要上传构件，后续 job 再下载，不能只保留本地目录。

只写了 download-artifact，为什么下载失败？通常是前置 job 没有成功上传、needs 未建立依赖，或两个动作的 name 不一致。先在运行摘要确认构件名称，再检查下载路径。

把“上传名、下载名、下载目录、needs 依赖”作为四个固定检查点，跨 job 传递构建结果就能稳定落地。