同一个版本号，测试台上的板子能连上，现场那块却连不上。两边都说用的是“v1.4”，聊天记录里还有三份同名的firmware.bin。这时再讨论谁的操作有问题，通常没有用，先要把设备、二进制和构建输入对应起来。
下面沿着一次假设的故障排查展开。清单和编号是说明用例，不是客户交付记录。
图：超维方程技术团队绘制。实线表示核对关系，不表示每个环节都能自动完成。
版本号给人看，构建标识用来定位
产品版本可以保持v1.4，但每次候选构建应有不同的构建标识。否则临时打开一项日志、改一份分区表、替换一个依赖以后，设备仍然只回答“我是 v1.4”。
一份发布记录至少要串起四件事：源代码是哪份，实际编出了哪些文件，测试针对哪份文件，设备现在运行哪份文件。清单可以很小，但不应把这些关系写成互不关联的备注。
{"release":"demo-v1.4","build_id":"demo-build-017","source_ref":"demo-reviewed-commit","dirty_worktree":false,"hardware_revision":"demo-board-B","config_record":"demo-config-017","partition_record":"demo-layout-02","artifact_manifest":"demo-artifacts-017","test_record":"demo-test-017"}这些值故意使用逻辑编号。实际发布时，应关联到受控归档中的提交号、配置文件、工具链版本和真实产物摘要；示例中的source_ref不能替代真实提交标识。
还要区分完整烧录包、应用 OTA 包、引导程序和分区表。有些文件能够单独升级，却不能拿来给一块空板完成初始化。文件名写清用途，比让接收者猜地址更可靠。
同一个提交号，不意味着相同二进制
排查到源码一致就停止，仍可能漏掉差异：未提交修改、依赖解析结果、构建配置、编译器版本，以及写进产物的时间和路径，都可能改变结果。
ESP-IDF 提供CONFIG_APP_REPRODUCIBLE_BUILD。官方文档说明它会处理部分路径和时间相关差异，但 SDK 与构建工具版本仍需一致；应用代码自己使用时间宏，也会影响可复现性。
因此需要分清两个验收目标：一是能够按记录重新构建并通过功能测试，二是能够重新构建出逐字节一致的文件。做到了前者，报告里就不要写成后者。
遇到不一致时，可以按下面的顺序缩小范围，而不是第一时间修改编译参数：
| 检查对象 | 先问的问题 |
|---|---|
| 源码与依赖 | 提交之外是否有本地修改？依赖是否真正锁定？ |
| 配置与分区 | 比较的是最终生效配置，还是只有默认配置？ |
| 工具链 | 编译器、SDK、构建工具版本是否一致？ |
| 产物生成 | 是否混入时间、路径或不稳定的输入顺序？ |
| 分发过程 | 测试文件和交付文件的摘要是否相同？ |
不要把内部构建目录、开发人员用户名或凭证直接装进公开清单。发布编号足以关联内部记录，公开追溯不等于公开整个开发环境。
最容易出错的是“测完再编一次”
假设构建 017 已通过测试，临发前为了关闭日志又产生了构建 018。即使只改一项配置，也不能把 017 的测试记录直接改名附给 018。
合理的处理是保留两个构建，记录差异，重新判断受影响的测试。关闭日志可能影响时序和内存占用，不能凭“功能代码没动”就断言行为相同。是否需要全量复测由变更范围决定，但记录不能假装没有变更。
这也是为什么摘要应在最后产物冻结后计算。摘要可以判断文件是否一致；它不能单独证明文件来自可信发布者。需要验证来源时，要另行建立签名及信任管理，不是把哈希字段换一个名字就够了。
从设备读回，而不是只看电脑上的文件
电脑上准备了一份包，不代表设备正在跑这一份。诊断入口至少应读回应用版本、构建标识和硬件适用信息，再与发布清单核对。多应用分区的设备还应能说明当前运行分区及待确认状态，避免把“下次准备启动的版本”当成“现在正在运行的版本”。
如果读回结果不一致，先保留证据：实际版本、上次升级结果、复现步骤及日志，再决定是否重新烧录。直接刷成最新版，也许能让故障暂时消失，却可能把定位所需的信息一起覆盖。
用一次交换文件的测试验收交付流程
可以在测试环境中准备两份同版本、不同构建的包，刻意交换其中一份。检查发布清单能否发现摘要不符，设备读回能否发现构建不符，测试报告能否明确拒绝沿用另一份结果。
再让没有参与构建的同事按交付说明复测。需要回头问作者才能确定的配置、地址或硬件适用范围，就是清单还没说明白的地方。
一份可维护的固件交付，不只是“文件能启动”，而是出现问题以后能回到同一组输入，知道上一次到底验证过什么。
参考资料：ESP-IDF Reproducible Builds。配置项和行为请对应项目实际 SDK 版本核查。
作者：超维方程技术团队。
