CI/CD / 系统课时
在阶段间传递临时制品
在阶段间传递临时制品
流水线的构建、测试和打包阶段可能运行在不同 Jenkins 节点,后一个阶段不能依赖前一个节点的工作目录。stash 与 unstash 可以把当前构建中的临时文件暂存并在后续节点恢复,适合传递体积不大的中间制品。
学习目标
- 理解工作空间不能跨节点直接共享的原因
- 使用
stash保存文件并通过unstash恢复 - 区分临时制品传递与长期制品归档
为什么阶段切换后文件会消失
Jenkins 的 workspace 属于执行该步骤的节点。若编译阶段运行在节点 A,而测试阶段被调度到节点 B,节点 B 的工作目录不会自动拥有节点 A 生成的文件。即使两个阶段都写着相同的相对路径,也不能把它理解为同一个磁盘目录。
stash 会把匹配的工作区文件保存为当前 Pipeline 运行期间可恢复的临时数据;后续阶段调用同名 unstash,Jenkins 会把这些文件解包到当前工作区。这样阶段只依赖一个逻辑名称,而不依赖前一个节点的本地路径。

在两个节点间传递文件
下面的 Declarative Pipeline 使用 agent none,让两个阶段分别申请执行节点。第一个阶段生成文件并执行 stash,第二个阶段先执行 unstash,再读取恢复后的文件。
pipeline {
agent none
stages {
stage('Build') {
agent any
steps {
sh '''
mkdir -p build
printf 'artifact-from-build\\n' > build/app.txt
'''
stash name: 'build-output', includes: 'build/**'
}
}
stage('Test') {
agent any
steps {
unstash 'build-output'
sh 'cat build/app.txt'
}
}
}
}预期输出
artifact-from-build实际控制台还会包含 Jenkins 的阶段、步骤和节点日志,因此完整日志文本会因 Jenkins 版本和执行环境不同而变化;关键验证结果是第二个阶段能够读取 build/app.txt。
控制保存和恢复的范围
stash name: 'build-output', includes: 'build/**' 中,name 是后续恢复时使用的逻辑名称,includes 使用 Ant 风格文件匹配规则选择要保存的内容。执行 unstash 'build-output' 时,文件按照原有相对目录结构恢复到当前 workspace。
同一条流水线需要传递多类文件时,应使用不同名称,例如分别保存编译产物和测试数据。名称应表达内容用途,避免多个阶段反复覆盖难以辨认的 stash。
什么时候改用归档或制品仓库
如果文件只需要从构建阶段传给同一次运行中的测试、扫描或打包阶段,stash/unstash 很合适。如果文件需要在构建结束后下载、审计或长期保存,应考虑 archiveArtifacts;如果还需要跨流水线、跨版本发布和管理大型二进制制品,则应使用专门的制品仓库。
因此,判断标准不是“文件是不是构建产物”,而是它的生命周期:只为当前 Pipeline 的后续阶段服务时使用 stash,需要成为可追踪的长期交付物时进入归档或制品管理系统。