CI/CD / 系统课时

构建成功但制品为什么不对

构建成功但制品为什么不对

Jenkins 显示构建成功,只能证明步骤按退出状态完成,并不能证明产出的 JAR、镜像或压缩包就是当前提交对应的制品。本节从工作目录、缓存、残留文件和版本信息入手,定位“流水线是绿的,交付物却错了”的问题。

学习目标

  • 区分构建成功与制品正确这两个独立结果
  • 排查工作区残留、缓存和错误路径造成的旧制品混入
  • 给制品加入可验证的提交版本信息,建立构建与源码的对应关系

先确认拿到的到底是什么

出现错误制品时,先不要立即重跑构建。应记录当前 Jenkins 构建号、Git 提交、制品文件名和校验值,再检查它们是否与预期版本对应。否则重跑可能覆盖现场,让问题更难复现。

常见现象包括:代码已经更新但 JAR 内容仍是旧版本、发布目录里同时存在多个历史包、归档步骤取错目录,以及缓存让某个生成步骤继续复用旧结果。

可以先在流水线中打印当前提交并检查实际产物。下面以 Maven 项目为例。

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

预期输出中的提交哈希、文件大小和时间会因实际构建而不同,因此使用动态占位符表示。

text
<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 校验制品。

groovy
stage('Verify Artifact') {
    steps {
        sh '''
            echo "commit=$(git rev-parse HEAD)"
            sha256sum target/*.jar
        '''
    }
}

这是 Jenkinsfile 的片段示例,依赖前序步骤已经检出 Git 仓库并生成 target 下的 JAR。预期输出中的提交 ID、哈希和文件名取决于实际项目。

text
commit=<ID>
<HASH>  target/<ARTIFACT>.jar

如果同一次构建记录的提交正确,但校验后的文件内容仍不符合预期,就应继续检查打包输入和生成过程;如果提交本身就不是目标版本,则应回到 SCM 检出、分支或参数选择环节,而不是继续研究打包工具。

用证据确认修复完成

修复后至少核对源码提交、干净构建产生的文件、归档路径和制品校验值。对于会部署到后续环境的制品,还应让部署阶段消费前面已经确认过的同一份归档,而不是重新从工作区按模糊文件名寻找。

“BUILD SUCCESS”描述的是流水线执行状态,而制品正确性需要额外证据。把提交 ID、确定的输出路径和校验值串起来后,才能回答一个关键问题:当前准备发布的二进制文件,是否真的由这次构建的这份源码产生。

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

目录与阅读设置

阅读设置

17

记录一个想法

构建成功但制品为什么不对

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

登录哪都通