两份固件都叫 v1.4，怎样查清设备实际烧了哪一份？

同一个版本号，测试台上的板子能连上，现场那块却连不上。两边都说用的是“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 与构建工具版本仍需一致；应用代码自己使用时间宏，也会影响可复现性。

因此需要分清两个验收目标：一是能够按记录重新构建并通过功能测试，二是能够重新构建出逐字节一致的文件。做到了前者，报告里就不要写成后者。

遇到不一致时，可以按下面的顺序缩小范围，而不是第一时间修改编译参数：

不要把内部构建目录、开发人员用户名或凭证直接装进公开清单。发布编号足以关联内部记录，公开追溯不等于公开整个开发环境。

最容易出错的是“测完再编一次”

假设构建 017 已通过测试，临发前为了关闭日志又产生了构建 018。即使只改一项配置，也不能把 017 的测试记录直接改名附给 018。

合理的处理是保留两个构建，记录差异，重新判断受影响的测试。关闭日志可能影响时序和内存占用，不能凭“功能代码没动”就断言行为相同。是否需要全量复测由变更范围决定，但记录不能假装没有变更。

这也是为什么摘要应在最后产物冻结后计算。摘要可以判断文件是否一致；它不能单独证明文件来自可信发布者。需要验证来源时，要另行建立签名及信任管理，不是把哈希字段换一个名字就够了。

从设备读回，而不是只看电脑上的文件

电脑上准备了一份包，不代表设备正在跑这一份。诊断入口至少应读回应用版本、构建标识和硬件适用信息，再与发布清单核对。多应用分区的设备还应能说明当前运行分区及待确认状态，避免把“下次准备启动的版本”当成“现在正在运行的版本”。

如果读回结果不一致，先保留证据：实际版本、上次升级结果、复现步骤及日志，再决定是否重新烧录。直接刷成最新版，也许能让故障暂时消失，却可能把定位所需的信息一起覆盖。

用一次交换文件的测试验收交付流程

可以在测试环境中准备两份同版本、不同构建的包，刻意交换其中一份。检查发布清单能否发现摘要不符，设备读回能否发现构建不符，测试报告能否明确拒绝沿用另一份结果。

再让没有参与构建的同事按交付说明复测。需要回头问作者才能确定的配置、地址或硬件适用范围，就是清单还没说明白的地方。

一份可维护的固件交付，不只是“文件能启动”，而是出现问题以后能回到同一组输入，知道上一次到底验证过什么。

参考资料：ESP-IDF Reproducible Builds。配置项和行为请对应项目实际 SDK 版本核查。

作者：超维方程技术团队。