CI/CD / 系统课时
上传构建产物供后续使用
上传构建产物供后续使用
构建完成后,如果生成的二进制包、前端目录或测试报告只留在 Runner 上,Job 结束时这些文件也会随运行环境消失。本节使用 workflow artifact 保存构建结果,使其可以被下载、审查或交给后续 Job 使用。
学习目标
- 使用
actions/upload-artifact上传指定文件或目录 - 理解 artifact 名称、路径和保留时间的作用
- 验证上传结果并处理路径匹配失败的问题
为什么要保存构建产物
GitHub Actions 的 Runner 通常是临时执行环境。以 Java 项目为例,mvn package 生成的 JAR 位于工作目录中,但 workflow 运行结束后不能把 Runner 当成长期文件存储使用。
Artifact 解决的是一次 workflow 运行中的文件留存与传递问题。常见对象包括构建包、前端 dist 目录、测试报告和覆盖率报告。它不同于源码提交,也不等同于正式的软件发布渠道。

在 workflow 中上传文件
下面的 workflow 先创建一个模拟构建包,再通过 actions/upload-artifact 上传。实际项目中,把创建文件的步骤替换为 Maven、Gradle、npm 等真实构建命令即可。
name: build-artifact
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Create build output
run: |
mkdir -p dist
printf 'demo build\n' > dist/app.txt
- name: Upload build artifact
uses: actions/upload-artifact@v4
with:
name: app-package
path: dist/
retention-days: 7name 是制品名称,后续下载时可以据此定位;path 指定上传文件或目录;retention-days 设置保留天数。目录中有多个文件时会一起上传,因此通常直接指向构建输出目录。
预期结果
Workflow 中的 build Job 成功完成,并产生名为 app-package 的 artifact,其中包含 app.txt。GitHub Actions 日志中的具体时间、内部路径和上传统计可能变化,应以本次运行页面显示为准。
上传多个类型的结果
一个 Job 可以调用多次 actions/upload-artifact,例如分别保存应用包和测试报告。这样比把所有文件混进一个制品更容易控制下载用途和保留策略。
路径还支持文件匹配模式。例如测试工具生成多个 XML 报告时,可以把 path 指向相应的 glob。无论采用目录还是模式,都应确保文件在上传步骤执行前已经真实生成。
验证与排查
上传步骤成功后,在对应 workflow run 的 artifact 区域应能看到 app-package。下载并解压后,应存在示例中的 app.txt。这比只看上传步骤显示成功更可靠,因为最终目标是确认需要的文件确实进入制品。
如果上传阶段提示找不到文件,先检查构建步骤实际输出位置,再检查 path 是相对于工作目录还是使用了错误的目录层级。不要通过忽略缺失文件来掩盖构建路径错误,否则流水线可能成功结束,却没有真正保存可用产物。
当产物只服务于当前流水线或短期调试时,workflow artifact 是直接且清晰的选择:构建步骤负责生成文件,上传步骤负责保存文件,两者职责分开后,后续测试、部署和人工下载都可以复用同一份构建结果。