CI/CD / 系统课时
清理工作区避免旧文件干扰
清理工作区避免旧文件干扰
Jenkins Agent 的工作区可能在多次构建之间复用,旧制品、缓存或上一次失败留下的文件因此可能进入下一次构建。本节从构建污染现象出发,使用 Jenkins Pipeline 清理工作区,并区分构建前清理与构建后清理的不同目的。
学习目标
- 识别工作区残留文件造成的典型构建污染
- 使用
deleteDir()在合适时机清理当前工作区 - 在可复现构建、缓存效率和故障调查之间选择清理策略
为什么旧文件会污染新构建
流水线如果假定“工作区每次都是空的”,而实际 Agent 复用了目录,就可能出现难以复现的问题。例如源码已经删除某个文件,但旧构建产物仍留在 dist/;新的打包命令又直接收集整个目录,最终制品便混入本次提交根本没有生成的内容。
另一种常见现象是失败构建留下中间文件,下一次构建恰好读取了这些文件,于是同一提交在干净环境中失败、在复用工作区中却成功。这类“幽灵成功”比直接失败更危险,因为它掩盖了构建过程对历史状态的依赖。
在检出前清理工作区
Pipeline 内置步骤 deleteDir() 会递归删除当前工作目录中的文件和目录。最直接的策略是在检出源码前清空工作区,使本次构建从已知状态开始。
pipeline {
agent any
stages {
stage('Clean and Checkout') {
steps {
deleteDir()
checkout scm
echo 'Workspace prepared'
}
}
stage('Build') {
steps {
sh 'mkdir -p build && printf "artifact\n" > build/app.txt'
}
}
}
}预期输出
Workspace prepared构建结束后,当前工作区会包含本次检出的源码以及 build/app.txt。具体绝对路径由 Jenkins 节点和 Job 配置决定,因此不应把固定工作区路径写死到脚本中。
如果步骤位于 dir('subdir') 中,deleteDir() 清理的是当前目录对应的工作区子目录。把它放在哪里,本身就是清理范围的一部分。
构建前清理还是构建后清理
构建前清理的目标是保证输入干净。它适合构建结果必须只由当前源码和显式依赖决定的任务,尤其适用于发布制品、容器镜像和容易受旧文件影响的编译过程。
构建后清理的目标则是释放空间并避免状态遗留。如果需要无论成功还是失败都执行,可以把清理放入 Declarative Pipeline 的 post 区域。下面是片段示例,需要加入已有 pipeline 的顶层 post 块。
post {
always {
deleteDir()
}
}它的生效行为是流水线结束时清空当前工作区。验证时可以在一次构建结束后检查对应 Agent 工作区,确认构建生成的临时文件不再保留。
缓存不要和工作区残留混在一起
完全清理虽然简单,但依赖下载、编译缓存等内容如果也放在工作区内,每次删除都会增加构建时间。更稳妥的做法是区分“可复用缓存”和“本次构建状态”:前者使用工具自身的缓存机制或专门缓存目录,后者保持可安全删除。
例如 Maven、Gradle、npm 等工具都有自己的依赖或构建缓存策略。是否保留这些缓存应由工具的缓存规则决定,而不是依赖“上一次工作区恰好没被删除”。发布制品也不应通过残留目录跨构建传递,应使用 Jenkins 的归档、stash/unstash 或外部制品仓库等明确机制。
验证清理是否解决污染
处理疑似工作区污染时,可以先记录失败现象,再手动执行一次干净构建进行对照。如果清理后问题消失,不应停在“以后都删目录”这个结论,还要继续找出流水线为什么读取了不属于当前构建的文件。
一个可靠的流水线应满足:相同源码、相同声明依赖和相同构建参数,在干净工作区中仍能得到预期结果。工作区清理是建立这个基线的手段,而不是替代依赖管理、制品管理和可复现构建设计。