CI/CD / 系统课时
上传与下载制品
上传与下载制品
这一课解决流水线阶段之间“文件怎么可靠交接”的问题:构建阶段上传一次,后续测试、部署阶段按明确名称下载,并同时控制路径、保留时间和访问边界,避免依赖某台 Runner 的临时工作目录。
学习目标
- 区分 Runner 工作目录与持久化制品存储,设计阶段间的制品交接。
- 为制品设置稳定名称、明确路径和合理有效期。
- 验证下载结果,并识别跨流水线、跨项目访问时的权限风险。
制品为什么必须先上传
CI/CD 的不同 Job 往往运行在不同 Runner 上。构建完成后留在本地工作目录里的 dist/,不能假设下一个 Job 还能看到;正确做法是把需要交接的文件上传到制品存储,再由下游按名称取回。

上传的对象应当是后续阶段真正需要的最小集合,例如编译产物、打包文件或测试报告,而不是整个仓库。这样既减少传输时间,也降低把密钥、缓存或无关临时文件带入后续阶段的风险。
设计名称、路径和有效期
名称用于让下游找到正确制品,建议表达制品职责和目标平台,例如 web-dist-linux-x64。名称不要只写 artifact,也不要把容易变化的工作目录路径当作名称。
路径决定实际上传什么。路径应在上传前存在,并尽量收敛到单一输出目录。若构建命令输出到 dist/,后续所有上传、校验和部署都围绕该目录,能明显减少“打包成功但上传空目录”的问题。
有效期取决于用途。短期流水线中间产物可以保留数天;发布包、审计证据或回滚基线则应进入更长期、受控的制品仓库。不要把 CI 的短期制品保留策略当成正式发布归档策略。
在流水线中上传再下载
下面以 GitHub Actions 展示同一工作流中两个 Job 的制品交接。构建 Job 生成文件并上传,下游 Job 通过 needs 等待构建成功,再按同一名称下载并校验内容。
name: artifact-transfer
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Build artifact
shell: bash
run: |
mkdir -p dist
printf 'build=%s\n' "$GITHUB_RUN_ID" > dist/app.txt
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: web-dist-linux-x64
path: dist/
retention-days: 7
if-no-files-found: error
verify:
needs: build
runs-on: ubuntu-latest
steps:
- name: Download artifact
uses: actions/download-artifact@v5
with:
name: web-dist-linux-x64
path: dist/
- name: Verify artifact
shell: bash
run: |
test -f dist/app.txt
cat dist/app.txt预期结果
build=<ID><ID> 是本次流水线运行 ID,实际值会不同。关键验收点不是具体数字,而是 verify Job 能在独立 Runner 上得到 dist/app.txt,证明文件来自制品存储而不是上一阶段的本地磁盘。
把权限边界放进设计
同一流水线内部的下载通常最简单;一旦跨工作流、跨仓库或跨项目读取,就要额外确认“谁能读哪个制品”。不要为了省事把制品仓库改成匿名可读,也不要把长期访问令牌直接写入 YAML。
如果平台支持细粒度权限,应优先授予只读下载权限,并把发布权限与普通构建权限分离。这样即使某个测试 Job 被滥用,也不应直接获得覆盖正式发布制品的能力。
验证交接而不是只看上传成功
上传步骤显示成功,只能说明平台接收了文件,不能证明下游拿到了“正确的那一份”。最小验证至少包括文件存在、关键文件数量或名称正确,以及必要时校验摘要或签名。
当下载失败时,按“名称是否一致 → 上游是否真的上传到目标路径 → 制品是否过期 → 当前身份是否有读取权限 → 是否引用了错误的流水线运行”这个顺序检查,通常比反复重跑更快定位问题。