CI/CD / 系统课时

清理工作区避免旧文件干扰

清理工作区避免旧文件干扰

Jenkins Agent 的工作区可能在多次构建之间复用,旧制品、缓存或上一次失败留下的文件因此可能进入下一次构建。本节从构建污染现象出发,使用 Jenkins Pipeline 清理工作区,并区分构建前清理与构建后清理的不同目的。

学习目标

  • 识别工作区残留文件造成的典型构建污染
  • 使用 deleteDir() 在合适时机清理当前工作区
  • 在可复现构建、缓存效率和故障调查之间选择清理策略

为什么旧文件会污染新构建

流水线如果假定“工作区每次都是空的”,而实际 Agent 复用了目录,就可能出现难以复现的问题。例如源码已经删除某个文件,但旧构建产物仍留在 dist/;新的打包命令又直接收集整个目录,最终制品便混入本次提交根本没有生成的内容。

另一种常见现象是失败构建留下中间文件,下一次构建恰好读取了这些文件,于是同一提交在干净环境中失败、在复用工作区中却成功。这类“幽灵成功”比直接失败更危险,因为它掩盖了构建过程对历史状态的依赖。

在检出前清理工作区

Pipeline 内置步骤 deleteDir() 会递归删除当前工作目录中的文件和目录。最直接的策略是在检出源码前清空工作区,使本次构建从已知状态开始。

groovy
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'
            }
        }
    }
}

预期输出

text
Workspace prepared

构建结束后,当前工作区会包含本次检出的源码以及 build/app.txt。具体绝对路径由 Jenkins 节点和 Job 配置决定,因此不应把固定工作区路径写死到脚本中。

如果步骤位于 dir('subdir') 中,deleteDir() 清理的是当前目录对应的工作区子目录。把它放在哪里,本身就是清理范围的一部分。

构建前清理还是构建后清理

构建前清理的目标是保证输入干净。它适合构建结果必须只由当前源码和显式依赖决定的任务,尤其适用于发布制品、容器镜像和容易受旧文件影响的编译过程。

构建后清理的目标则是释放空间并避免状态遗留。如果需要无论成功还是失败都执行,可以把清理放入 Declarative Pipeline 的 post 区域。下面是片段示例,需要加入已有 pipeline 的顶层 post 块。

groovy
post {
    always {
        deleteDir()
    }
}

它的生效行为是流水线结束时清空当前工作区。验证时可以在一次构建结束后检查对应 Agent 工作区,确认构建生成的临时文件不再保留。

缓存不要和工作区残留混在一起

完全清理虽然简单,但依赖下载、编译缓存等内容如果也放在工作区内,每次删除都会增加构建时间。更稳妥的做法是区分“可复用缓存”和“本次构建状态”:前者使用工具自身的缓存机制或专门缓存目录,后者保持可安全删除。

例如 Maven、Gradle、npm 等工具都有自己的依赖或构建缓存策略。是否保留这些缓存应由工具的缓存规则决定,而不是依赖“上一次工作区恰好没被删除”。发布制品也不应通过残留目录跨构建传递,应使用 Jenkins 的归档、stash/unstash 或外部制品仓库等明确机制。

验证清理是否解决污染

处理疑似工作区污染时,可以先记录失败现象,再手动执行一次干净构建进行对照。如果清理后问题消失,不应停在“以后都删目录”这个结论,还要继续找出流水线为什么读取了不属于当前构建的文件。

一个可靠的流水线应满足:相同源码、相同声明依赖和相同构建参数,在干净工作区中仍能得到预期结果。工作区清理是建立这个基线的手段,而不是替代依赖管理、制品管理和可复现构建设计。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

清理工作区避免旧文件干扰

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通