📚 课程目录第3章升级包版本管理

3、升级包版本管理：语义化版本号、兼容性矩阵与回滚触发条件

版本管理这事儿，看着简单，做起来全是坑。我见过太多团队，升级包版本号随便写个 v1.2、v3.0beta，结果设备升级出问题，连哪个版本该回滚到哪都搞不清楚。说白了，版本号不是给程序员看的，是给升级系统做决策用的。

这一章，咱们就把版本管理的三个核心问题讲透：版本号怎么编、兼容性怎么管、回滚什么时候该触发。

语义化版本号，英文叫 SemVer，全称 Semantic Versioning。它的格式很简单：主版本号.次版本号.修订号，比如 2.1.3。

但规则才是关键。我直接给你看标准定义：

主版本号：做了不兼容的 API 或协议变更
次版本号：新增了向下兼容的功能
修订号：做了向下兼容的问题修复

在 OTA 场景里，这个规则要稍微调整一下。举个例子，我做过一个智能门锁项目，固件从 v1.2.0 升到 v1.3.0，只是加了远程临时密码功能，协议没变，这就是次版本升级。但如果从 v1.x 升到 v2.0.0，意味着通信协议改了，旧版 App 连不上新固件，这就是主版本升级。

我的经验：修订号升级，必须保证 100% 无感。用户甚至不该知道固件更新过。次版本升级，允许有功能变化，但不能破坏已有行为。主版本升级，必须走完整的兼容性测试流程，而且通常要保留双区回滚能力。

还有一个容易被忽略的点：预发布版本。比如 2.0.0-alpha.1 或 1.5.0-rc.2。我建议，预发布版本只用于内测或灰度，绝对不能推给正式设备。为什么？因为预发布版本不保证兼容性，一旦出问题，回滚逻辑可能都跑不通。

小技巧：在升级包的元数据里，除了版本号，还要记录一个 build_metadata 字段，比如 2.0.0+build20240315。这样即使版本号相同，也能区分不同构建，方便排查问题。

版本号定好了，接下来要回答一个问题：从版本 A 升到版本 B，到底能不能直接升？

这就是兼容性矩阵要做的事。说白了，它是一个二维表格，行是当前版本，列是目标版本，交叉点标记是否允许直接升级。

我直接画一个典型的矩阵示例：

当前版本 \ 目标版本	v1.0.0	v1.1.0	v1.2.0	v2.0.0
v1.0.0	-	✅ 直接升	✅ 直接升	❌ 需先升到 v1.2.0
v1.1.0	❌ 不支持降级	-	✅ 直接升	❌ 需先升到 v1.2.0
v1.2.0	❌ 不支持降级	❌ 不支持降级	-	✅ 直接升
v2.0.0	❌ 不支持降级	❌ 不支持降级	❌ 不支持降级	-

你看，这个矩阵有几个关键信息：

我在一个车载项目里就吃过这个亏。当时没做兼容性矩阵，直接允许 v1.0.0 升到 v2.0.0，结果升级后中控屏黑屏。查了半天，发现 v2.0.0 改了显示驱动接口，v1.0.0 的旧驱动没做适配。从那以后，我要求每个版本发布前，必须更新兼容性矩阵，并且由测试团队签字确认。

注意：兼容性矩阵不是静态的。每次发布新版本，都要重新评估所有历史版本到新版本的兼容性。我见过有些团队偷懒，矩阵半年不更新，结果灰度升级时炸了一片。

回滚不是你想回就能回的。触发条件必须明确、可量化、自动化。我把它分成三类：

这类条件由升级系统自动检测，不需要人工干预：

这类条件需要云端或运维人员介入：

单一条件触发回滚，有时候会误伤。我建议用“与/或”逻辑组合：

回滚触发 = (升级超时 OR 心跳丢失) AND (启动失败 OR 自检失败)

举个例子：设备升级后心跳正常，但自检失败。这种情况可能是某个非关键模块出问题，不一定需要回滚。但如果心跳丢失并且启动失败，那基本可以确定升级有问题，必须回滚。

我的建议：回滚触发条件要分等级。一级条件（如启动失败 + 心跳丢失）立即触发回滚，不需要人工确认。二级条件（如灰度异常率超标）先暂停升级，通知运维人员确认后再决定是否回滚。三级条件（如用户投诉）走人工流程。

嗯，这里还要注意一个细节：回滚本身也可能失败。所以触发回滚后，系统要记录回滚结果，如果回滚也失败了，设备要进入“安全模式”或“救援模式”，等待人工处理。

下面这张图，把版本管理的三个核心模块串起来了。你可以看到，版本号是基础，兼容性矩阵是规则，回滚触发条件是兜底。三者缺一不可。