做开发的这些年我几乎天天都要跟版本号打交道。每次听到三个经典版本新同事第一反应都是懵到底是哪三个是 1.0、2.0、3.0还是开发版、测试版、正式版这个问题看着基础真答清楚的没几个。我在几个项目组里摸爬滚打之后可以负责任地说所谓三个经典版本第一层是版本号的三段式结构第二层是三种发布形态第三层是三种对应的管理动作。这篇就把这三层一次讲透适合刚入行的开发、兼职管发布的负责人以及所有被版本混乱坑过的人。1. 三个经典版本到底指哪三个1.1 第一层三段式版本号先讲最直白的一层。任何规范的软件版本号基本都长成 X.Y.Z 这样比如 1.0.0、2.1.3、3.14.2。这个三段结构就是三个经典版本在数字层面的体现每一段有各自的含义主版本号X发生不向后兼容的变化时递增。接口删了、数据结构改了、配置格式变了都算。次版本号Y向后兼容的新功能、能力增强时递增。旧功能还能用只是多了新东西。修订号Z向后兼容的缺陷修复、细微调整时递增。只修问题不改变既有行为。这个三段式不是谁拍脑袋定的它来自一整套被广泛采用的语义化版本规范。核心价值不是好看而是让每个看到版本号的人能在不看文档的情况下判断两件事这个版本能不能直接升升级有没有风险打个比方版本号就像药品包装上的批次信息。同一种药批次变了你放心用剂型改了要看说明书如果大类都变了主治方向可能都不同了。版本号把大类、剂型、批次压缩成了三个数字就是为了让这个判断在一秒钟内完成。1.2 第二层三种经典发布形态如果只有数字还是不够。因为同一个版本号在开发中和上线后含义完全不同。于是就有了第二层三个经典版本开发版、稳定版、维护版。开发版是功能还在动的形态。接口天天变今天能跑明天可能崩它面向的是内部测试和早期反馈不面向普通用户。稳定版是功能冻结、经过完整回归测试、可以放心对外发布的形态。维护版则是在稳定版发布之后只修复严重问题、不再加新功能的状态。这三者不是三个独立的分支更像是同一份代码在不同阶段、不同受众面前的三张脸。我见过太多团队把这三张脸混在一起用户拿到的所谓稳定版其实就是某天深夜的开发版打包。这就是发布形态没分清楚的结果。1.3 第三层三种对应的管理动作理解了两种含义还不够因为版本管理最终要落到动作上。第三个三个经典版本指的是三种形态各自对应的管理动作版本形态版本号写法管理动作受众开发版2.1.0-dev.20240115持续构建不冻结功能内部测试、早期反馈稳定版2.1.0冻结功能打不可变标签全体用户维护版2.1.1、2.1.2独立分支只修不改无法升级的存量用户开发版靠构建序号识别稳定版靠标签锚定维护版靠分支隔离。这三条动作线一旦理清后面所有规则就都有了落点。2. 三段式版本号的规则设计与升级策略2.1 三问定版什么时候升哪一位我在团队里定了一条三问定版的口诀。每次准备发版本先回答三个问题这次有没有改变既有行为有没有删接口、改数据结构、改配置格式、改返回结果答有升主版本号。如果没有破坏兼容那有没有加新功能答有升次版本号。如果只是修 bug、调样式、优化性能且行为完全不变答有升修订号。三个问题都答没有就不该发版本继续攒需求。举个例子一个叫模拟项目X的跨平台图像处理工具当前版本 2.1.3。修复了某个页面的崩溃问题行为不变发 2.1.4。新增了批量导出功能旧接口全部保留发 2.2.0修订号归零。重构了滤镜渲染管线旧接口参数全部更换发 3.0.0次版本号和修订号全部归零。这里有新人常踩的一个坑以为 2.2.0 只是在上一个基础上加了点东西实际在语义化版本规范里每次升次版本号修订号必须归零。如果不归零你很快会看到 2.2.13 和 2.3.7 这种没法排大小、没法对比先后的混乱局面。归零不是形式主义是为了让版本号保持严格的大小关系。2.2 版本号背后的兼容性承诺版本号不只是给自己看的更是给上下游看的。假设你维护一个被多个团队依赖的基础组件你的版本号就是一份对外承诺书修订号变化只修问题所有调用方可以无感升级。次版本号变化加了能力但旧调用不被破坏调用方可以放心升。主版本号变化有破坏性变更调用方需要规划迁移不能直接升。这就像租房子。房东换了个灯泡你继续住没问题房东加装了一个阳台你住着更舒服但租金可能有变化房东把一居室改成两居室原来的格局全变你得重新考虑要不要续租。这里最容易被忽视的是行为变更也算破坏性变更。有的团队觉得接口没删就不算破坏于是把某个接口的返回顺序改了、把某个错误码改了然后只升了个修订号。调用方看到 1.4.9 以为是修修补补升级后却发现多了一个不想要的行为。我在维护一个老组件时吃过这个亏那次之后我规定任何对外可见的行为变化哪怕接口签名没动也得升次版本号并在变更日志里明确标注。2.3 预发布版本号alpha、beta、rc 怎么放三段式规则只能描述已经发布的状态但稳定版发布之前还有一个灰度过程。这时就用到预发布版本号最常见的三种后缀是alpha内部功能验证版功能不全接口随时变。beta功能基本齐了公开给测试群体试用收集反馈。rc候选发布版功能冻结只修阻断性问题如果没问题就直接转正式版。预发布版本号的标准写法是挂在修订号后面比如 2.0.0-alpha.1、2.0.0-beta.2、2.0.0-rc.1。注意预发布版本的优先级永远低于正式版本。也就是说2.0.0-alpha.99 依然排在 2.0.0 的后面这是规范里明确规定的目的就是防止有人拿预览版冒充正式版。我建议小团队只保留 beta 和 rc 两个阶段就够了。alpha 阶段如果团队内部就能消化不必对外开放否则版本号后缀太多光维护这些命名就够让人头疼的。2.4 一次完整版本路线的复盘为了把规则串起来我复盘了模拟项目X一年半的版本路线版本号类型关键变更说明1.0.0稳定版首版发布包含裁切、滤镜、缩放对外打标签1.1.0次版本新增批量处理旧接口全部保留1.1.1修订版本修复内存溢出只改实现不改行为2.0.0主版本重构滤镜管线提前半年通知提供迁移工具2.1.0次版本新增插件系统旧接口未动2.1.3修订版本修复插件加载失败特定系统路径问题这条路线里最值得学习的是 2.0.0 的处理。不能某天心血来潮就升主版本号而是提前规划先做兼容层、先开发迁移工具、先通知所有调用方约定一个迁移窗口期。很多项目死在主版本号随缘升——破坏性变更做完直接发布整个调用生态鸡飞狗跳。3. 一个项目的三个经典版本是怎么走出来的3.1 开发版阶段让版本号跟着迭代快走开发版阶段的目标是快速验证、快速试错版本号不要太纠结。我推荐一个做法开发版统一用正式版本号 dev 日期或序号的写法比如 2.1.0-dev.20240115或者 2.1.0-dev.18。核心是让任何一个人一眼看出这个开发版比上一个新而不用去翻提交记录。为什么要带日期或序号因为纯靠提交哈希来区分对测试同学太不友好。测试拿到一个构建连是哪天的都不知道出了问题都没法定位。带上日期或序号之后测试可以精确反馈今天这个 dev.20240115 比昨天的 dev.20240114 多了一个崩溃。就这一条排查效率能提升一大截。另外开发版千万别占用正式的三段式空间。你要是把开发版叫 2.1.0后面正式版也叫 2.1.0线上日志就成了一锅粥没法分辨用户用的是开发版还是正式版。我的习惯是开发版永远带后缀正式版永远干净两者严格区分不带任何含糊。3.2 从开发版到稳定版功能冻结与完整回归从开发版走到稳定版中间不是点一下按钮的事。我整理了一条硬性流程每个步骤都不能跳冻结功能。明确这个版本包含哪些需求、不包含哪些需求。临时加需求是稳定版发布最大的灾难。完整回归。跑核心用例尤其是上一版本承诺过的兼容场景。新增功能可以出 bug但承诺过的功能退步是不可接受的。更新变更日志。把新增、修复、破坏性变更写清楚用户升级前一定会看这个。修改版本号并提交。版本号统一在代码配置里改好提交一次不和功能代码混在一起。打发布标签、归档构建产物。把可执行文件、依赖清单、校验值一起保存日后排查问题要用。功能冻结这一步最容易出问题。很多团队嘴上说冻结实际上线前一天还往里塞需求。一旦这么干了回归测试的范围就无限膨胀稳定版变成测不完的版。我见过最夸张的一次某个项目组连续发了三个稳定版每一个都带着临时加的需求结果每一个都需要紧急补丁。从那之后我规定稳定版发布前 48 小时冻结功能冻结之后任何新需求都排到下个版本没有例外。3.3 稳定版发布版本号、标签、构建产物三对齐稳定版发布那一刻要做的事情可以浓缩成一句话让代码里的版本号版本标签指向的提交实际发布的构建产物三者完全一致。具体操作上我会按这个顺序执行# 1. 把版本配置从开发版改为正式版 # 例如2.1.0-dev.20240115 - 2.1.0 # 2. 单独提交版本号变更 # 提交信息写明release: 2.1.0 # 3. 打一个带注释的不可变标签 tag -a v2.1.0 -m release: 2.1.0 # 4. 从标签拉出维护分支 branch -c v2.1.0-stable这里有一个细节标签一旦打出去就不要移动、删除、重建。经常有人发现打错标签顺手把旧标签删了再打一个新的结果所有已经拉取过代码的同事本地标签和远程对不上。宁可再补打一个补救性质的标签也不要动原来的标签。标签是发布的历史锚点锚点一改整个历史就乱了。3.4 维护版阶段只修不改稳定版发布不代表这个版本的生命结束了后面的维护期才是最考验纪律的阶段。维护期的第一原则是只修不改严重的崩溃、安全漏洞、数据损坏问题才值得发维护版。新功能、需求变更一律排到下一个次版本或主版本。原因很简单维护版的受众是那些因为各种原因没法升级的用户你贸然加功能等于逼他们在安全修复和功能变化之间做选择这不是维护这是添乱。维护期还要明确维护期限写进项目文档。是维护一年、两年还是跟随下一个主版本发布后停止必须说清楚。我见过一个老项目三个版本同时在维护每个版本都要打补丁团队被拖垮最后所有版本都没维护好。正确的做法是一次最多维护两个版本当前稳定版和上一个稳定版。再老的版本统一引导用户升级不能无限兜底。4. 在项目里真正落地版本管理4.1 分支、标签、版本号的配合关系版本管理不能只靠改一个数字它需要和代码组织方式配合。我习惯的分支与版本对应关系是这样的版本形态代码位置具体做法开发版主分支日常开发都提交到主分支版本号带 dev 后缀稳定版主分支上的标签从主分支打标签标签作为不可变节点维护版独立维护分支从稳定版标签拉出分支只允许修复提交这套结构的好处是清晰主分支永远在往前跑标签把每个发布时刻钉死维护分支负责兜底。三者互不干扰。很多团队的问题在于把维护工作也做在主分支上结果主分支上同时存在新功能和旧补丁代码越来越乱最后连稳定版是从哪拉出来的都说不清。4.2 一个发布日的完整操作记录分享一个典型的稳定版发布日时间线照着这个顺序走基本不会翻车上午功能冻结代码进入只修阻断性问题的状态。同时把变更日志整理完列出新增、修复、破坏性变更。下午跑完整回归。核心用例全部执行一遍记录执行人和结果。发现问题就修修完补测对应场景。傍晚修改版本号单独提交。提交信息写清楚release: x.y.z。打发布标签归档构建产物记录产物编号和校验值。发布后第一时间验证核心链路确认线上版本号和代码、标签一致。更新发布记录表。这套流程里最容易被压缩的是发布后验证。很多团队发布完就下班了第二天用户报 bug 才发现线上有问题。我现在的习惯是发布后至少在核心链路上手动走一遍哪怕只是确认服务正常启动、登录功能可用也能避免绝大多数低级事故。4.3 变更日志怎么写才不白写变更日志是版本管理的人话层它不应该复制粘贴提交记录而应该按用户能理解的语言分类。我常用的模板## [2.1.0] - 2024-01-15 ### 新增 - 支持批量导出图片 - 新增插件系统可加载外部滤镜 ### 修复 - 修复高 DPI 屏幕下工具栏错位 - 修复特定系统路径下插件加载失败 ### 破坏性变更 - 无注意破坏性变更这一栏很多人觉得我们这个版本没有破坏性变更就不写了。但我强烈建议保留哪怕写无。因为用户读到无的那一刻才会确认升级是安全的。空着不写用户就要自己猜一通乱猜就会去翻源码这是最糟糕的用户体验。另外变更日志要做两件事按版本号倒序排列最新的在最上面每个版本都要有发布日期。没有日期的版本号半年之后你就想不起来这个版本是什么时候发的排查问题时非常痛苦。4.4 发布检查清单每次发布前建议照着清单过一遍比任何口头叮嘱都管用版本号是否在代码配置里统一修改配置、启动横幅、接口返回的版本字段是否一致变更日志是否更新并且指向当前版本号回归测试是否完成用例是否有执行人和结果构建产物是否包含正确的依赖版本依赖锁定文件是否已提交旧版本标签和构建产物是否可找回发布后是否第一时间验证了核心链路这份清单里最容易漏的是接口返回的版本字段。很多项目的版本号散落在前端展示、后端接口、管理后台里漏掉任何一个用户和管理员看到的版本就不一样排查问题时就会得出完全相反的结论。我吃过一次亏之后每次发布前都会专门搜一遍代码里的版本号引用点挨个确认。5. 常见问题与排查经验5.1 版本号冲突两个人同时改了版本号多人协作时最常见的冲突就是A 同事把版本号改成了 2.1.4 并提交B 同事在本地也把版本号改成了 2.1.4提交时冲突。这种冲突看着小处理不当会让版本号悄悄回退。我的经验是版本号文件的修改要单独提交不要和功能代码混在一起。功能代码可以随意合并但版本号这种全局唯一的信息最好由一个人统一管。如果团队很小那就约定谁准备发布谁在发布前最后一个改版本号改完立刻通知所有人版本号已定勿动。5.2 回滚了代码版本号却没回滚生产环境出了问题紧急回滚到上一个版本但刚才发布时改的版本号还留在代码里。这时候线上跑的是旧代码报告的却是新版本。排查问题的同学一看日志以为线上是新版查了半天才发现是回滚后的旧版白白浪费一两个小时。解决办法是建立发布记录表每次发布写一行发布时刻、版本号、构建产物编号、回滚后的状态。没有发布记录的项目版本管理就是空中楼阁。回滚不丢人丢人的是回滚之后说不清楚现在线上到底是什么版本。5.3 标签与构建产物不一致还有一种很隐蔽的问题标签指向的提交和实际发布出去的构建产物不一致。比如发布流程是先打包再打标签结果打包之后又有人提交了一个紧急修改标签打完产物却还是旧的。我的排查思路是任何一次发布都要能回答三个问题这个构建产物是从哪个提交构建的这个提交有没有对应的版本标签这个版本标签是否等于当前代码里的版本号三个问题中任何一个答不上来这次发布就是不可信的。答得上来就把这三个信息写进发布记录作为唯一的发布凭据。下次再出问题靠这条记录就能快速定位。5.4 依赖地狱版本范围与锁定文件版本管理不只要管自己发的版本还要管依赖的版本。很多项目出问题不是自己代码错了而是依赖了一个非常宽泛的版本范围导致不同环境的依赖版本不一致。我的建议就一句话锁定依赖版本提交锁定文件。开发环境和发布环境必须用同一份依赖版本。这个问题最典型的表现是本地跑得好好的测试环境一编译就挂了。查到最后往往是某依赖在中间版本引入了不兼容变更。锁定之后这类问题基本绝迹。当然锁定依赖不代表永远不升级而是让升级变成一次显式的、有记录的、经过回归的动作而不是环境里随机发生的事件。5.5 给新手的快速排查口诀最后分享一个排查版本问题的口诀叫先看号再看签最后看标记先看号看代码里的版本号是不是你预期的那一个。再看签看版本标签是不是指向了你预期的那次提交。最后看标记看构建产物有没有日期标记能不能和发布记录对上。按这个顺序查大部分版本混乱的问题十分钟内就能定位是改错了号、打错了签还是发错了包。不要一上来就翻日志、猜原因先按顺序核对这三个信息往往比盲目排查高效得多。这些年折腾下来我最大的体会是版本管理从来不是技术问题是纪律问题。三个经典版本——三段式版本号、三种发布形态、三份对应的管理动作——说穿了就是一套让什么时候能变、什么时候不能变变得可预期的规矩。规矩越简单团队越能坚持。如果你正被版本混乱折磨别急着上多复杂的工具链先把三件事做对版本号按规则升、发布前走清单、发布后留记录。就这三条能解决你身边一大半的版本纠纷。最后再啰嗦一句版本号是写给别人的契约不是写给自己看的日记。你每一次对版本号的随意最后都会变成用户和同事的一笔糊涂账。