GitLab CI 制品（Artifacts）完全指南：从作用到配置实践

GitLab CI 制品Artifacts完全指南从作用到配置实践一、Artifacts 的核心作用1.1 什么是 Artifacts1.2 Artifacts 与 Cache 的本质区别1.3 Artifacts 的三大应用场景二、Artifacts 基础配置2.1 基本语法结构2.2 核心配置字段详解2.3 高级配置条件上传与排除三、常见场景配置示例3.1 Java/Maven 项目3.2 JavaScript/Node.js 项目3.3 Python 项目3.4 二进制/通用项目四、在作业间传递 Artifacts4.1 使用 dependencies 下载特定作业的制品4.2 使用 needs 优化执行顺序五、测试报告与可视化5.1 JUnit 测试报告5.2 代码覆盖率报告5.3 代码质量报告Code Quality六、最佳实践6.1 控制制品大小6.2 制品命名规范6.3 敏感信息处理6.4 制品过期策略七、总结The Begin点点关注收藏不迷路⬇ ⬇ 底部 ⬇ ⬇ 在 CI/CD 流水线中作业之间的数据传递和构建结果的保存是常见需求。GitLab CI 的artifacts机制正是为此而生——它允许作业在完成后将文件或目录持久化保存供后续作业使用或供开发者下载查看。本文将全面解析 artifacts 的核心作用、配置方法及最佳实践。一、Artifacts 的核心作用1.1 什么是 ArtifactsArtifacts制品是 GitLab CI 中用于在作业之间传递文件或目录的机制。当一个作业执行完成后可以通过artifacts关键字将指定的文件或目录上传到 GitLab 服务器供同一流水线的后续作业下载使用或通过 GitLab Web 界面直接下载查看。形象理解可以把 Artifacts 想象成流水线上的接力棒——前一阶段Job的工作成果编译好的二进制文件、测试报告等通过它传递给后一阶段确保整个流水线可以无缝衔接。1.2 Artifacts 与 Cache 的本质区别理解了 artifacts 和 cache 的区别才能正确使用两者对比维度 制品Artifacts 缓存Cache核心用途在阶段间传递构建结果加速依赖下载存储位置GitLab 服务器Runner 本地或 S3 缓存后端跨流水线❌ 不跨流水线默认仅本流水线可见✅ 跨流水线共享生命周期默认 30 天可配置长期存在按 key 刷新缺失影响后续作业无法运行不影响功能仅速度下降典型内容编译产物、测试报告、安装包node_modules/、vendor/、pip cache核心原则Artifacts 是必须存在的结果传递Cache 是可有可无的速度优化。不要用 artifacts 传递依赖缓存也不要用 cache 传递关键构建结果。1.3 Artifacts 的三大应用场景⬇️ 手动下载构建产物开发者本地验证测试人员提取安装包运维人员获取配置文件️ 可视化查看测试报告JUnit XML 渲染为表格覆盖率报告 渲染为图表代码质量报告 显示问题 Artifacts 三大场景Job间传递编译: .jar/.war测试: JUnit XML部署: 容器镜像/包典型应用示例编译作业 → 打包作业前端构建产出dist/后续部署作业使用测试作业 → 报告展示单元测试生成junit.xmlGitLab 自动渲染为测试报告构建作业 → 手动下载开发者从 GitLab 下载构建好的 APK 或 JAR 包二、Artifacts 基础配置2.1 基本语法结构job:artifacts:paths:# 要上传的文件或目录必须-target/*.jarname:my-artifact# 下载时的压缩包名称expire_in:1 week# 过期时间reports:# 特殊报告类型junit:junit.xml2.2 核心配置字段详解字段类型说明pathsArray要上传的文件或目录路径支持通配符必须指定nameString下载时的压缩包名称默认artifacts.zipexpire_inString过期时间默认 30 天如1 week或30 daysreportsMap特殊报告类型JUnit、覆盖率、代码质量等whenString上传时机on_success/on_failure/alwaysexcludeArray排除特定文件从 paths 中剔除publicBoolean是否公开可见公开项目可用私有项目无效带所有字段的完整示例build:script:-mvn clean package-mvn testartifacts:paths:-target/*.jar-target/surefire-reports/name:$CI_COMMIT_REF_NAME-$CI_COMMIT_SHORT_SHAexclude:-target/**/*.log# 排除所有日志文件expire_in:30 daysreports:junit:target/surefire-reports/TEST-*.xmlwhen:on_successpublic:true2.3 高级配置条件上传与排除条件上传whentest:script:-npm run testartifacts:when:always# 无论成功或失败都上传paths:-test-results/deploy:script:-npm run deployartifacts:when:on_failure# 仅当失败时上传便于排障paths:-logs/排除特定文件excludebuild:artifacts:paths:-dist/-coverage/exclude:-dist/**/*.map# 排除所有 map 文件-coverage/**/*.html# 排除 HTML 报告三、常见场景配置示例3.1 Java/Maven 项目build:stage:buildscript:-mvn clean packageartifacts:paths:-target/*.jar-target/surefire-reports/reports:junit:-target/surefire-reports/TEST-*.xmlexpire_in:1 week3.2 JavaScript/Node.js 项目build:stage:buildscript:-npm install-npm run build-npm test----coverage--watchAllfalseartifacts:paths:-dist/# 构建产物-coverage/# 覆盖率报告reports:junit:junit.xmlcoverage_report:coverage_format:coberturapath:coverage/cobertura-coverage.xmlexpire_in:1 week3.3 Python 项目build:stage:buildscript:-pip install-r requirements.txt-python setup.py sdist bdist_wheel-pytest--junitxmlreport.xmlartifacts:paths:-dist/# 打包后的 wheel 文件-.pytest_cache/reports:junit:report.xmlexpire_in:1 week3.4 二进制/通用项目build:stage:buildscript:-go build-o myapp-./run_tests.shartifacts:paths:-myapp# 可执行文件-test-reports/-configs/# 配置文件目录name:$CI_PROJECT_NAME-$CI_COMMIT_REF_NAME-$CI_COMMIT_SHORT_SHAexpire_in:30 days四、在作业间传递 Artifacts4.1 使用dependencies下载特定作业的制品默认情况下流水线中各阶段的作业会自动接收所有前置阶段的 artifacts。使用dependencies可以精确控制下载哪些作业的 artifactsstages:-build-test-deploybuild:stage:buildscript:-mkdir binary-echo 构建产物binary/appartifacts:paths:-binary/test:stage:testscript:-echo 测试artifacts:paths:-test-reports/dependencies:[]# 不下载任何 artifactsdeploy:stage:deployscript:-ls-la binary/-echo 部署dependencies:-build# 仅下载 build 作业的 artifacts4.2 使用needs优化执行顺序结合needs关键字实现更精细的依赖关系允许作业无需等待所有前置阶段完成即可开始build_app_a:stage:buildscript:echo 构建 Aartifacts:paths:-dist_a/build_app_b:stage:buildscript:echo 构建 Bartifacts:paths:-dist_b/deploy_a:stage:deployneeds:[build_app_a]# 只依赖 build_app_a不需要等待 Bscript:echo 部署 Adependencies:-build_app_adeploy_b:stage:deployneeds:[build_app_b]script:echo 部署 Bdependencies:-build_app_b五、测试报告与可视化5.1 JUnit 测试报告GitLab 自动识别reports: junit路径下的 XML 文件在 MR/流水线页面渲染为测试表格test:script:-npm test----watchAllfalseartifacts:reports:junit:-junit.xml-test-results/**/*.xml5.2 代码覆盖率报告test:script:-npm test----coveragecoverage:/All files[^|]*\|[^|]*\s([\d\.])/# 提取覆盖率数值artifacts:reports:coverage_report:coverage_format:coberturapath:coverage/cobertura-coverage.xml5.3 代码质量报告Code Qualitycode_quality:stage:testscript:-docker run--env SOURCE_CODE$PWD...codeclimateartifacts:reports:codequality:gl-code-quality-report.json六、最佳实践6.1 控制制品大小只上传必要的文件避免上传整个node_modules/或target/除非必要使用exclude排除不需要的日志、临时文件设置合理的expire_in时间如开发构建 1 天发布构建 30 天6.2 制品命名规范使用 CI 变量使制品名称包含上下文信息artifacts:name:$CI_PROJECT_NAME-$CI_COMMIT_REF_NAME-$CI_COMMIT_SHORT_SHApaths:-build/6.3 敏感信息处理不要将包含密码或密钥的文件作为 artifacts 上传使用CI_JOB_TOKEN进行制品下载认证私有项目默认可见性仅为项目成员6.4 制品过期策略场景建议过期时间日常开发构建1 day或3 days功能分支构建1 weekRelease 构建30 days或never测试报告1 week七、总结核心要点说明核心作用在作业间传递构建产物供后续作业使用或手动下载与 Cache 的区别Artifacts 用于必须传递的结果Cache 用于可有可无的加速关键字段paths必填、name、expire_in、reports、when传递方式默认所有前置阶段可用通过dependencies精确控制报告集成JUnit、覆盖率、代码质量报告自动渲染到 MR 页面最佳实践控制制品大小、设置过期时间、避免上传敏感信息核心启示GitLab CI 的 artifacts 机制是连接流水线各环节的桥梁。它将阶段化的工作成果有序传递让构建、测试、部署各司其职又环环相扣。正确的使用方式是编译阶段产出二进制文件 → 测试阶段依赖这些文件运行 → 部署阶段使用测试通过的版本进行发布。这种清晰的依赖关系正是现代化 CI/CD 流水线的核心设计理念。The End点点关注收藏不迷路⬆ ⬆ 顶部 ⬆ ⬆