5.5 可复现构建：同一份代码同一份结果

5.5 可复现构建：同一份代码同一份结果

本节摘要：可复现构建指同一 commit 在任何时间、任何机器上构建出字节级或语义级一致的产物。三要素是版本全锁定、禁 SNAPSHOT 进发布、构建环境一致。版本号策略用表达式加 flatten 插件解决，产物一致性靠禁漂移配置与校验和归档验证。本节给出三要素清单与验证方法。

"复现不出来"的四种结局

第 3.6 节的随机漂移故障暴露了一个残酷事实：多数团队的构建结果不能复现。它的四种结局都见过：线上出包要回溯，重新构建的包与线上不是同一个（字节不同，回溯失真）；审计要求提供某版本的确切产物，仓库里的与当时的对不上校验和；安全扫描报的是当时包里的漏洞，如今重建的包漏洞面变了；不同环境"同版本"包行为不同，排查两小时发现是两次构建的产物本来就不一致。

可复现构建的定义先立清楚：同一个 commit，在任何时间的任何机器上构建，产物一致（严格派要求字节级一致，务实派接受"依赖集与语义一致"）。要达到它，三要素缺一不可。

三要素清单

要素一：版本全锁定。 依赖版本、插件版本、父 POM 版本，全部显式钉死（第 3.3 与 5.4 节已建制）。残余风险在"区间版本"与"未管理传递依赖"，用 enforcer 的收敛门禁兜住。

要素二：发布链路禁 SNAPSHOT。 SNAPSHOT 的语义就是"随时变"，带它发布的包天然不可复现。军规化：

<!-- 父 POM：enforcer 给发布分支上闸 -->
<rules>
  <requireReleaseDeps>
    <!-- 出现在发布构建时 任何 SNAPSHOT 依赖直接失败 -->
    <onlyWhenRelease>true</onlyWhenRelease>
  </requireReleaseDeps>
</rules>
​

要素三：环境一致。 JDK 版本、Maven 版本、语言环境（时区与编码）。JDK 用 toolchains 机制声明式锁定（项目写清楚"用哪个 JDK 构建"，机器只负责装好它），Maven 版本用 wrapper 机制锁定（项目自带构建器版本定义文件，每人每机跑同一版）。编码在第 2 章的 POM 里已统一为 UTF-8，时区在打包类插件里显式声明，避免产物里烙上构建机器的本地时间。

版本号策略：表达式与 flatten

多模块发布有个经典矛盾：发布时要给全部模块打同一个版本号，手工改几十处版本字面量易错且丑。惯例是版本表达式化：

<!-- 各模块 POM 的版本统一引用修订号 -->
<version>${revision}</version>

<!-- 构建时注入 -->
<!-- mvn clean deploy -Drevision=2.3.0 -->
​

表达式的问题在发布产物里会原样出现 ${revision} 字样，下游读到的是坏坐标。解法是 flatten 插件：打包前把有效 POM 摊平成"字面量版本"的形态发布：

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>flatten-maven-plugin</artifactId>
  <version>1.5.0</version>
  <configuration>
    <!-- 摊平策略：解决版本表达式 保留发布需要的信息 -->
    <flattenMode>resolveCiFriendliesOnly</flattenMode>
  </configuration>
  <executions>
    <execution>
      <id>flatten</id>
      <phase>process-resources</phase>
      <goals>
        <goal>flatten</goal>
      </goals>
    </execution>
  </executions>
</plugin>
​

验证：怎么证明"可复现"

制度要有验证手段才算闭环。三级验证从宽到严：

# 一级 语义验证：同一 commit 两次构建的依赖树一致
mvn dependency:tree -DoutputFile=t1.txt
# 变更缓存状态后（清 lastUpdated 加 -U）再构建一次 出 t2.txt
# 比对 t1 与 t2： RELEASE 依赖集必须完全一致

# 二级 产物验证：校验和归档比对
# 每次发布把产物的校验和归档到发布记录
# 任意时刻重建 同 commit 的产物校验和应与归档一致

# 三级 字节验证：可复现打包模式
# 打包插件启用可复现模式（固定的归档条目时间戳等）
# 排除构建机器的时钟与文件系统顺序对产物的影响
​

三级验证的成本与深度递增，接入建议也分级：一级写进流水线的每日任务（自动跑、失败告警），二级挂在发布流程（发布脚本顺手归档校验和），三级只在有合规诉求时立项。每一级都对应一个真实事故场景——一级防"依赖漂移"、二级防"产物调包疑云"、三级防"审计级质疑"，按你团队实际会遇到的质疑等级投入。

三级里一二级是务实基线，建议全团队达标；三级是理想态，个别高合规场景才追。验证必须定期做——它检测的是整套制度的持续有效性，一次达标不代表永远达标（一次引入未锁定的传递依赖就破了功）。

可复现性的自检三问，季度评审时过一遍：

问一：随机抽一个三个月前的发布版本 能在今天重建出校验和一致的产物吗？
问二：两位工程师同一时刻构建主干 依赖树输出一致吗？
问三：CI 节点换新机器后 构建结果与旧机器一致吗？
​

三问全过，可复现性是制度；一问不过，它就还只是愿望。第 6 章要讲的构建加速（远程缓存）以这三问为前提——缓存机制的本质假设就是"同输入同输出"，假设不成立的缓存，是错误结果的高速分发网络。> ⚠️ 常见坑：把"构建成功"当作"构建可复现"。前者是当次的结果，后者是结果的稳定性。团队最容易在连续绿灯几个月后悄悄破功——某个新依赖没进管理段、某台新 CI 机的 JDK 版本不同。定期跑一次二级验证，破功点十分钟内现形。

💡 关键直觉：可复现性是信任的压缩包。发布记录、审计、漏洞响应、故障回溯，全部压在"这个版本号能确切对应一份产物"这个前提上。三要素的建造成本两三天，它支撑的是此后每一次"讲证据"的场合。

战报小结

• 定义：同 commit 任何时间任何机器构建产物一致，语义级是务实基线，字节级是理想态；
• 三要素：版本全锁定（依赖加插件加父 POM）、发布链路禁 SNAPSHOT（enforcer 上闸）、环境一致（toolchains 加 wrapper 加编码时区）；
• 版本表达式配 flatten：revision 表达式解决批量改版本，摊平插件修掉坏坐标；
• 三级验证：依赖树一致、校验和归档、可复现打包模式，定期执行检测制度有效性；
• 可复现性是信任基础设施：审计与回溯的每个"讲证据"场合都踩着它。

构建的制度线全部闭合。最后一节把质量维度补上——SonarQube 质量雷达：它怎么接进流水线，扫描什么，门禁怎么拦。