如何通过Gitlab-CI Artifacts在Linux环境中实现构建产物跨阶段传递及存档？

本文共计715个文字，预计阅读时间需要3分钟。

在Linux环境下，利用GitLab CI的artifacts实现构建产物跨阶段传递与归档，核心是两件事：

配置 artifacts 保存构建产物

在生成文件的作业（如 build）中明确声明要归档的路径：

• paths 指定相对项目根目录的文件或目录，支持通配符，例如：
  artifacts: paths: - dist/ - build/app.jar
• 建议避免 **/* 这类宽泛匹配，只保留真正需要的产物，节省存储和传输开销
• 可选设置 expire_in: 7 days 控制保留时长，防止测试构建长期占用空间
• 若只在成功时归档，无需额外写 when: on_success（这是默认行为）

让下游作业自动获取这些产物

后续阶段（如 test 或 deploy）默认会自动下载前一阶段所有作业的 artifacts，但更稳妥的做法是显式声明依赖：

• 在下游作业中添加 dependencies: [build]，确保只拉取指定作业的产物
• GitLab 会在作业开始前，把 build 作业归档的文件解压到当前工作目录，路径结构保持原样
• 如果多个构建作业并行（如 build:linux 和 build:osx），下游可通过不同 dependencies 分别引用

区分用途：传递 vs 归档 vs 下载

同一个 artifacts 配置可同时满足三种需求，关键看怎么用：

• 传递给下游：靠 dependencies 触发自动下载，无需额外脚本
• 人工下载查看：流水线运行完成后，在 GitLab Web 界面进入对应 job → 点 “Download artifacts” 按钮，获得 ZIP 包
• API 自动下载：用 curl 调用 /jobs/:id/artifacts 接口，配合 PRIVATE-TOKEN 获取二进制流
• 注意：artifacts 不跨 pipeline，只对同一 pipeline 内的 job 有效

避免常见陷阱

有些看似合理但实际失效的做法需要绕开：

• 不要依赖 GIT_CHECKOUT: false 来“复用”上一阶段文件——它要求所有 job 必须跑在同一 runner 上，生产环境通常不满足
• 不要在 script 里用 cp 或 rsync 手动搬运产物，既冗余又易错
• cache 不适合传递构建产物，它是为依赖包等高频小文件设计的，命中不确定，且不保证一致性
• 路径必须是相对路径，不能写 /tmp/output 或绝对路径，否则归档失败静默忽略