版本管理基础：语义化版本（SemVer）详解、版本号与兼容性承诺

你想想看，一个SDK发出去，用户那边集成得好好的。突然有一天你修了个小bug，把版本号从1.2.3改成1.2.4。用户升级后整个系统崩了。谁的问题？

说白了，版本号不是个简单的数字递增。它是一种承诺。我个人习惯，每次改版本号之前都会问自己：这次改动会不会让用户断开？会不会需要用户改代码？

语义化版本（SemVer）长什么样？

它是一套标准，格式很简单：主版本号.次版本号.修订号。比如 2.3.1。

每个数字背后都有严格的含义。我刚开始做SDK时吃过一次亏：把接口签名改了，却只升了修订号。结果用户旧代码直接编译不过。嗯，后来再也不敢这么干了。

位置	名称	含义	什么时候改
第一位	主版本号（MAJOR）	做了不兼容的API修改	删了公开方法、改了方法签名、返回值变化
第二位	次版本号（MINOR）	新增了向下兼容的功能	加了新接口、新类、新字段，不破坏旧的
第三位	修订号（PATCH）	向下兼容的问题修复	修bug、性能优化、内部实现调整

你看，这三段就是三档不同的风险等级。用户只需扫一眼版本号，就能知道升级代价有多大。

扩展规则：预发布和构建元数据

有时候你需要在正式版之前先放个beta版给内部测试。SemVer也考虑到了：1.0.0-alpha.1，在修订号后面加连字符，再接一串标识符。

构建元数据用加号，比如 1.0.0+20250301。注意：构建元数据不影响版本优先级，预发布版本的优先级低于正式版。

版本号与兼容性承诺——一张表说清楚

用户最关心的是升级后自己代码要不要改。我把每个版本号变化对应的「用户行动」整理成了一张表。这张表我常贴在工位上，发版前对照着看一遍。

版本号变化示例	对用户的影响	用户升级建议
1.2.3 → 2.0.0	API不兼容，编译报错、运行时异常	必须修改代码，建议先读变更日志
1.2.3 → 1.3.0	新增功能，旧接口完全保留	可以放心升级，旧代码无需改动
1.2.3 → 1.2.4	修复bug，行为优化，接口不变	推荐升级，风险极低
1.2.3 → 1.2.3-alpha.1	内部测试版本，接口可能随时变	仅用于集成验证，不要上生产

为什么要这么明确？我曾经在一次发版前，因为赶时间，把一个大重构标记成了次版本号升级。结果用户升级后疯狂报错，那周我光挨骂就挨了三天。从那以后，我发版前一定会对照这张表自检一遍。

实战中的常见陷阱

1. 陷阱一：把非兼容改动藏在PATCH里
   比如修了一个bug，顺带改了某个方法的返回值类型。严格来说这应该升主版本号。但很多人偷懒只升PATCH。用户升级后一脸懵：我什么代码都没动，怎么突然编译不过了？
2. 陷阱二：预发布版本号越升越高，忘记清空
   1.0.0-alpha.99，然后正式版还是1.0.0。预发布版本内部依赖链混乱，CI都跑不对。我见过一个项目预发布版本号打到了300多，正式版迟迟不发。
3. 陷阱三：0.x.y阶段不守规矩
   SemVer规定，主版本号为0时，任何改动都可能不兼容。很多团队在0.x阶段任意修改API，又不上次版本号。结果用户根本不敢用你的SDK，版本号等于没写。
4. 陷阱四：构建元数据影响版本比较
   注意，1.0.0+build1 和 1.0.0+build2 在SemVer优先级上是相等的。如果你依赖npm的版本范围解析，它可能会把两个都当成同一个版本，导致升级混乱。

版本号声明的最佳实践

• 用工具管理版本号 ：semver命令行工具或者IDE插件，自动校验版本号格式和变化。
• 变更日志与版本号一一对应 ：每次发版都维护CHANGELOG，说明每个版本改动了什么、是否兼容。
• CI里加版本号合规检查 ：如果这次PR改了公共API，CI自动检查版本号是否跟着涨了。我习惯用Python写个脚本，对比前后两个版本的API签名差异，不符则阻断发版。
• 内部SDK也遵循SemVer ：很多团队觉得内部用随便标一标就好。但你想想看，微服务之间互相依赖，一个内部SDK乱改版本号，整个调用链都会受影响。

版本号这件事，说小也小，就是个字符串；说大了，它是你整个SDK对外沟通的“合约”。每一次版本号的变更，背后都是对用户的承诺——我用这个数字，告诉你该不该升级、怎么升级。把这套规则用好了，后期兼容测试能减少八成不必要的排查时间。