CI/CD / 系统课时
构建成功但制品为什么不对
构建成功但制品为什么不对
Jenkins 显示构建成功,只能证明步骤按退出状态完成,并不能证明产出的 JAR、镜像或压缩包就是当前提交对应的制品。本节从工作目录、缓存、残留文件和版本信息入手,定位“流水线是绿的,交付物却错了”的问题。
学习目标
- 区分构建成功与制品正确这两个独立结果
- 排查工作区残留、缓存和错误路径造成的旧制品混入
- 给制品加入可验证的提交版本信息,建立构建与源码的对应关系
先确认拿到的到底是什么
出现错误制品时,先不要立即重跑构建。应记录当前 Jenkins 构建号、Git 提交、制品文件名和校验值,再检查它们是否与预期版本对应。否则重跑可能覆盖现场,让问题更难复现。
常见现象包括:代码已经更新但 JAR 内容仍是旧版本、发布目录里同时存在多个历史包、归档步骤取错目录,以及缓存让某个生成步骤继续复用旧结果。
可以先在流水线中打印当前提交并检查实际产物。下面以 Maven 项目为例。
pipeline {
agent any
stages {
stage('Checkout') {
steps {
checkout scm
sh 'git rev-parse HEAD'
}
}
stage('Build') {
steps {
sh 'mvn -B clean package'
sh 'ls -lh target/*.jar'
}
}
}
}预期输出中的提交哈希、文件大小和时间会因实际构建而不同,因此使用动态占位符表示。
<ID>
-rw-r--r-- 1 jenkins jenkins <SIZE> <TIME> target/<ARTIFACT>.jar这里最重要的不是文件存在,而是确认构建使用的提交与待发布版本一致,并且后续归档或部署步骤读取的确实是这个 target 目录中的新文件。
排查工作区和残留文件
Jenkins 工作区可能被后续构建复用。如果构建命令没有清理输出目录,旧文件可能继续留在磁盘上。尤其是使用 *.jar、dist/* 等宽泛模式复制制品时,一个历史文件就可能被误选。
优先检查构建命令是否包含可靠的清理阶段。例如 Maven 使用 mvn clean package 会先删除 target 再重新打包,比只执行 mvn package 更适合验证是否存在旧输出干扰。
还要核对每个步骤的当前目录。Jenkinsfile 使用 dir('backend') 后,其中的相对路径都以该目录为基准;构建发生在一个目录、归档却从另一个目录取文件,同样可能得到旧制品。
区分依赖缓存和构建输出
缓存本身并不是问题。Maven 本地仓库、npm 缓存或 Docker 构建缓存通常用于减少重复下载和计算;真正需要判断的是缓存中哪些内容可以安全复用,哪些输出必须由当前源码重新生成。
排查时可以做一次受控对照:保留依赖缓存,但清理项目构建输出,然后重新构建。如果制品恢复正确,问题更可能来自工作区残留或增量构建;如果仍然错误,则继续检查源码检出、生成脚本、依赖版本和制品选择路径。

把源码版本写进验证链
仅靠文件名中的版本号并不足以证明制品来源。更可靠的做法是让构建记录 Git 提交 ID,并在归档前输出制品校验值。这样即使两个文件名称相同,也可以判断二进制内容是否发生变化。
下面的步骤可放在 Linux Jenkins Agent 的构建阶段之后,用 SHA-256 校验制品。
stage('Verify Artifact') {
steps {
sh '''
echo "commit=$(git rev-parse HEAD)"
sha256sum target/*.jar
'''
}
}这是 Jenkinsfile 的片段示例,依赖前序步骤已经检出 Git 仓库并生成 target 下的 JAR。预期输出中的提交 ID、哈希和文件名取决于实际项目。
commit=<ID>
<HASH> target/<ARTIFACT>.jar如果同一次构建记录的提交正确,但校验后的文件内容仍不符合预期,就应继续检查打包输入和生成过程;如果提交本身就不是目标版本,则应回到 SCM 检出、分支或参数选择环节,而不是继续研究打包工具。
用证据确认修复完成
修复后至少核对源码提交、干净构建产生的文件、归档路径和制品校验值。对于会部署到后续环境的制品,还应让部署阶段消费前面已经确认过的同一份归档,而不是重新从工作区按模糊文件名寻找。
“BUILD SUCCESS”描述的是流水线执行状态,而制品正确性需要额外证据。把提交 ID、确定的输出路径和校验值串起来后,才能回答一个关键问题:当前准备发布的二进制文件,是否真的由这次构建的这份源码产生。