3. 量产软件版本治理基础
在 S32K3 这类车规级 MCU 的量产项目中，版本治理不是“给文件起个名字”这么简单。一个 ECU 项目往往同时存在多个硬件变体（例如同一块 PCB 上是否装配以太网 PHY、是否使用外部 SBC、Flash 容量是 2MB 还是 4MB），又存在多个软件变体（Bootloader 是否带 CAN FD、应用是否启用 OTA、标定数据是否区分高低配）。如果版本号、构建元数据和变体映射没有统一规则，就会出现“同一版本号对应不同二进制”“同一硬件烧错软件”“问题复现时找不到对应源码”等典型量产事故。本节围绕四件事展开：版本号规范、语义化版本、构建元数据、硬件变体与软件变体映射。
一、版本号规范：先定义“谁在变”
版本号规范的核心是回答三个问题：这个号标识的是哪个对象？它由谁生成？它如何与源码、构建产物、发布记录一一对应。在 S32K3 项目中，建议把版本对象分成三层：
- 项目版本：整个 ECU 软件包的对外版本，例如
S32K3_ECU。 - 组件版本：Bootloader、Application、标定数据、诊断数据库等独立交付单元。
- 构建版本：某一次 CI 构建产生的唯一标识，用于追溯具体二进制。
版本号本身建议采用“主版本.次版本.修订号”三段式，并附加构建元数据。主版本在接口不兼容、硬件平台切换或诊断协议大改时递增；次版本在功能新增但保持兼容时递增；修订号在缺陷修复、参数调整、文档更新时递增。关键原则是：版本号只增不减，已发布版本号不得复用。一旦某个版本号已经烧录到样件或量产件，即使发现错误，也只能发布新的修订号，不能覆盖原版本。
二、语义化版本：让版本号携带兼容性信息
语义化版本（Semantic Versioning）在量产软件中的价值，是让下游工具链和整车厂能够仅凭版本号判断“能不能直接替换”。以 2.4.1 为例：
2是主版本，表示存在不兼容变更，例如诊断服务 ID 重新分配、NVM 布局改变，升级时必须同步更新刷写脚本和标定数据。4是次版本，表示新增功能但向后兼容，例如新增一个 DID 读取项，旧诊断仪仍可正常工作。1是修订号，表示兼容性修复，例如修正 CAN 报文周期抖动，接口和功能范围不变。
在 S32K3 的 CI 流程中，语义化版本不应由人工随意填写，而应由发布分支和变更类型自动推导。例如：合并到 release/2.x 的缺陷修复提交，CI 自动将修订号加一；合并到 main 且带有 feat: 标签的提交，自动提升次版本；带有 BREAKING CHANGE 的提交，必须人工确认后提升主版本。这样版本号本身就成了一份可审计的兼容性声明。
三、构建元数据：把“哪一次构建”钉死
语义化版本描述的是“发布意图”，构建元数据描述的是“这一次构建的事实”。推荐格式为：
2.4.1+20250612.3.g7a1c9f2
其中 2.4.1 是语义化版本，+ 之后是构建元数据：20250612 是构建日期，3 是当天第 3 次构建，g7a1c9f2 是 Git 提交短哈希。构建元数据不参与版本比较，但必须唯一。它应被写入：
- 编译产物的
.elf/.hex/.bin文件名； - 软件内部的版本常量，可通过 UDS 服务
0x22读取 DID0xF189； - CI 归档目录和发布记录；
- 刷写日志与诊断报告。
这样当整车厂反馈“某台车在低温下 CAN 通信偶发丢帧”时，只需读取 DID 即可定位到具体提交，而不是在几十个二进制中猜测。构建元数据还应包含编译器版本、优化等级和关键宏定义，例如 GCC 10.3.1 -O2 -DENABLE_OTA=1，因为同一份源码在不同编译选项下可能产生不同行为。
四、硬件变体与软件变体映射
硬件变体通常由硬件版本号或配置电阻编码标识，例如 HW_A、HW_B、HW_C。软件变体则由编译宏和配置数据决定，例如 SW_BASE、SW_CANFD、SW_OTA。映射关系必须显式定义，不能靠“默认都能跑”。
推荐用一张映射表固化关系，并在 CI 中自动校验：每个软件变体只能烧录到允许的硬件变体上；每个硬件变体至少有一个经过验证的软件变体。下表为示例，参数为合理假设：
| 硬件变体 | 硬件特征 | 允许软件变体 | 关键编译宏 |
|---|---|---|---|
| HW_A | 2MB Flash，无以太网 | SW_BASE | HW_A=1, ETH=0 |
| HW_B | 4MB Flash，带以太网 | SW_BASE, SW_OTA | HW_B=1, ETH=1 |
| HW_C | 4MB Flash，带以太网与 CAN FD | SW_CANFD, SW_OTA | HW_C=1, CANFD=1 |
映射关系还应体现在刷写工具中：刷写前读取硬件版本，若与软件变体不匹配则拒绝刷写；刷写后回读软件版本和硬件版本，写入生产追溯系统。对于 OTA 场景，服务器下发升级包时必须携带目标硬件变体列表，ECU 端校验不通过则丢弃升级包，避免“刷成砖”。
五、落地要点与常见陷阱
第一，版本号必须由 CI 自动生成，禁止手工修改。手工版本号是追溯断链的最大来源。第二，构建元数据必须写入二进制内部，不能只存在于文件名或发布记录中，因为文件名可以被重命名，而 DID 回读不会。第三，硬件变体与软件变体的映射表应作为受控文档纳入版本管理，任何新增变体都必须同时更新映射表和 CI 校验规则。第四，语义化版本的“兼容性”判断需要团队共识，建议在代码评审清单中明确列出哪些变更属于主版本、次版本和修订号，避免各人理解不一致。
常见陷阱：用同一版本号重新构建并覆盖发布包。即使源码相同，编译器版本、构建时间或宏定义不同，二进制也可能不同。正确做法是每次构建都生成新的构建元数据，旧构建包只归档不覆盖。
实践建议：在 S32K3 的链接脚本或启动代码中预留版本信息段，将语义化版本、构建元数据、硬件变体 ID 和软件变体 ID 以结构体形式固化到 Flash 固定地址，Bootloader 和 Application 均可读取。这样刷写工具、诊断仪和产线追溯系统都能用同一套接口获取版本信息，减少协议转换和人工录入错误。
总结来说，版本治理的基础不是某一个工具，而是一套从源码到整车的可追溯规则：语义化版本表达兼容性，构建元数据锁定唯一构建，硬件与软件变体映射防止错刷。三者结合，才能在 S32K3 量产项目中做到“任何一个二进制都能回答它从哪来、能烧到哪、改了什么”。