企业官网建设流程全解析

1. 为什么要把版本号当回事

做软件这么多年，我越来越觉得版本号是项目里最容易被忽视、却又最能体现工程素养的东西。很多团队前期完全不规划版本，随手npm publish一个1.0.0，后面发布全靠感觉，等到出问题的时候，依赖方拿着一个说不清来路的版本号来问，双方都很痛苦。

SemVer（Semantic Versioning，语义化版本）解决的就是这件事：给版本号定一套明确的规则，让大家看到版本号就知道这个版本带来了什么变化、能不能放心升级、会有什么风险。它本质上不是约束，而是项目之间沟通的“信用体系”。

这篇文章我会把 SemVer 的三个数字段、预发布规则、实际操作中怎么判断该升哪一位、常见的坑、以及如何在团队和 CI 流程里真正落地，一条一条讲透。如果你维护的是公共库、命令行工具、基础组件，或者哪怕只是自己项目里的内部模块，这套规则都值得花一晚上读明白。

先看一个最基础的版本号格式：

主版本号.次版本号.修订号

比如2.14.3，主版本号是2，次版本号是14，修订号是3。每一个数字的递增都有明确的触发条件，不是随手改的。

2. SemVer 三段数字的设计逻辑

2.1 主版本号：破坏性变更的信号枪

主版本号递增，意味着这个版本不再向后兼容。也就是说，依赖方之前用的 API、配置格式、行为约定，在这个版本里可能被改掉了、删掉了或者换了个写法。

举个例子：某个图像处理库1.x里resize()接收的是(width, height)，到2.0.0改成(options)对象。依赖方升级到2.0.0之后，原来的调用代码会直接报错或行为不对，这就是典型的破坏性变更。这个时候就必须升主版本号，而不是藏在次版本号或者修订号里混过去。

实际开发里有个很不好的习惯：主版本号长期不动，新功能、破坏性改动全部靠次版本号往上堆。比如6.2.1到6.3.0里其实包含了一个删 API 的变更，依赖方扫描升级后线上崩了。这个问题的根源是团队对“破坏性”没有共识，觉得“内部用没人看版本号”“改了就改了没必要大动干戈”。但一旦这个库被多个项目依赖，这种偷懒就会成倍放大。

判断是不是破坏性变更，我一般用三个标准：

• 被公开的 API 是否被删除、改名或改变参数签名
• 某个行为的默认结果是否发生变化（比如原来返回数组，现在返回对象）
• 配置文件、环境变量、数据结构是否不再兼容旧格式

只要三条里占了一条，就该认真考虑主版本号递增。注意是“至少占一条就升”，不是“三条全占才升”。

2.2 次版本号：向后兼容的新功能

次版本号递增，代表在保持兼容的前提下增加了新功能。依赖方升级到新版本之后，旧代码应该依然能正常工作。

比如1.4.2升级到1.5.0，新增了一个convert()方法，但原来所有的方法都原样保留，参数和行为不变。这种升级对依赖方来说是安全的（除非之前依赖某种内部 bug 行为，这个后面讲）。

新功能是否只能出现在次版本号里？严格来说是的。修订号对应的版本只应该修问题，不应该引入新的对外能力。如果修复过程中需要新加一个对外接口才能解决问题，那这次发布应该至少算次版本号更新，不能算修订号更新。

实操中有个容易混淆的点：新功能如果还带着@beta或者experimental标签，算不算次版本号？我个人的做法是：只要这个 API 正式对外可调用，就算。哪怕标记了“未来可能变更”，也依然是一次功能新增，升次版本号。experimental只是降低用户对稳定性的预期，不代表它可以藏进修订号里。

2.3 修订号：修 bug 而不改行为

修订号递增的唯一触发条件是：向后兼容的 bug 修复。也就是说，版本从3.8.1到3.8.2，只修了一个崩溃问题、一个误报的逻辑、或者一个边缘 case 的处理，原有 API 不变、行为定义不变，只是让它更符合预期。

需要特别注意，“修 bug”引发的行为变化很可能被依赖方视为破坏性变更。比如之前某个函数在参数为空时返回null，依赖方可能已经基于这个“bug”写了自己的判断逻辑。你现在修成返回空数组，从规范和你的视角都是“修正错误”，但依赖方视角是“返回类型变了”。这种修复如果影响面大，需要评估是否需要单独发一个大版本，或者至少在 changelog 里显著标注。

政治站位上的建议是：修订号版本里尽量收敛，不要夹带新功能、重构、样式调整等和“修 bug”无关的东西。否则依赖方很难判断升级风险。我自己见过有人把“升级数据库驱动”“格式化代码”“顺手加了个 header”全塞进一个1.2.4修订版里，那次的排查过程相当痛苦。

2.4 预发布版本和构建元数据

版本号后面常见的-alpha.1、-beta.2、-rc.1就是预发布版本标识。它们表示这个版本还没达到正式发布标准，但已经可以供部分用户提前尝鲜。

优先级规则必须理解准确：1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-rc.1 < 1.0.0。

这个排序看起来有点绕，核心逻辑是：SemVer 的优先级不是按照字符串字典序简单比较，而是按分隔符点号拆分后逐段比较数字和字母的优先级。数字标识符之间按数值比较，字母或数字混合的标识符按字典序比较，数字标识符总是低于非数字标识符。

最常见的一个错误是使用-beta.10和-beta.9时候，有人按字符串排序以为beta.10小于beta.9，但 SemVer 规则里按数值比较，10 > 9，所以1.0.0-beta.10优先级高于1.0.0-beta.9。这类问题在发布排序、依赖解析和自动化脚本里很容易踩。

构建元数据用+号追加，比如1.0.0+build.20250101。它的作用是携带编译信息，不影响版本优先级。同一版本号的两个构建版本优先级一样，只是标识不同。实际使用中不推荐把构建号作为区分版本的手段，它更合适给 CI 流水线做追溯。

3. 版本号怎么定：实操规则与判断标准

3.1 升级主版本号的场景和成本

升级主版本号不是小事，它会给所有依赖方发送一个“需要关注”的信号。在我维护的项目里，升级主版本时一定需要走 review 流程，至少要确认：

• changelog 里列出所有破坏性变更，给出迁移路径
• 示例代码、文档、测试用例同步更新
• 在 release note 里明确说明废弃 API 的替代方案

有些项目会采取“先标记废弃，再大版本删除”的策略。比如在4.x里标注@deprecated，在5.0.0里真正移除。这样给依赖方留足了迁移时间。这是我最推荐的做法，成本低很多，也更容易获得用户理解。

主版本号升到0之外的另一个作用是建立“用户对该项目稳定性的预期”。1.0.0意味着 API 进入稳定状态，之后每次变化都要遵循 SemVer。长期停留在0.x的公共库会让依赖方心里打鼓，因为0.x阶段允许随时破坏变更，但用户也会怀疑你连 1.0 都不敢发，是不是项目太不稳定。

3.2 升级次版本号的场景和细节

次版本号升级是所有发布里最常见的。新增功能、增加可选参数、扩充返回值字段，基本都落在次版本号。

这里有个值得展开的细节：新功能是“向后兼容”还是“伪兼容”。比如新加了一个参数options.format，默认值还是老行为，这是兼容的；但如果新参数改变了默认输出格式，这就是行为变更，需要仔细评估。常见的不兼容还有：新功能导致启动时的初始化逻辑变化、默认并发数变化、日志格式变化。这些都不在“新增 API”的范畴，但确实可能影响依赖方，要不要升主版本号，得靠测试和沟通来确认。

实操中我一般先写测试用例，新增功能的测试如果必须在旧版本上改断言才能通过，那么大概率还是别藏在次版本号里了。凡是“升级后行为完全不同”的，即便表面没删 API，也该走主版本号。

3.3 升级修订号的场景和细节

修订号升级应该是最频繁、最安全、也最容易被忽视纪律的发布类型。它只应包含能覆盖回归测试的 bug 修复。项目如果做得好，修订号的版本之间唯一差异就是修复内容和对应的测试，其他一概不动。

我习惯在合并 MR 的时候就判断发布属性：

• 修复类型是 bug fix，不涉及行为重新定义 → 修订号
• 新增导出函数/方法/组件 → 次版本号
• 删除导出或语法上不兼容 → 主版本号

这个习惯坚持下来之后，整个项目的发布流程变得非常机械化，不需要每次发布前反复开会讨论版本号。版本号是一个工程决策的产物，不是拍脑袋的“第三个数字加一”。

3.4 0.x 阶段的特殊规则

0.x版本的 SemVer 规则和>=1.0.0稍有不同：0.x允许破坏性变更，且不需要升主版本号。例如0.3.0可以直接升级到0.4.0并包含破坏性变更，因为用户使用0.x时已经默认接受不稳定的预期。

但我要提醒，0.x阶段不等同于可以随便发布破坏性变更而不通知。至少要在文档中写明，当前处于不稳定阶段，并在 changelog 里给出变更说明。实践中最忌讳的是：某个项目长期0.x，然后某天发布0.30.0时悄悄改了一堆公开 API，没有提示没有迁移指南。这会让社区对该项目的信任快速降低，因为它虽然合法（按 SemVer 的 0.x 规则），但非常不合情理。

4. 实战中容易踩的坑

4.1 依赖锁死 vs 浮动版本

版本号的意义在依赖管理场景中体现得最充分。以 JavaScript 生态为例，package.json里写^1.4.0表示允许安装1.x.x的最新版本。如果某天项目发布1.5.0（次版本号，按 SemVer 承诺向后兼容），依赖方升级应该没有风险。但如果发布方只是形式上升了次版本号，实际行为是破坏性的，所有依赖方都会被波及。

被这个问题打脸之后我意识到：不要完全信任依赖方会管理好版本范围。作为库的维护者，在需要高风险变更时，即使按 SemVer 属于次版本号，也在 release note 里以显著位置提示“如果你依赖了某些内部行为，建议先测试再升级”。这不是规范强制要求，但这是工程素养。

作为依赖方，我也养成了一个习惯：package-lock.json或等价锁文件必须提交到仓库，并定期更新依赖时跑完整测试。凡是核心公共库升级主版本号，先读 changelog，找破坏性变更对应的替代写法，再决定升级节奏。

4.2 版本号滥用：0.0.x 和频繁主版本

有两个比较极端的现象值得一提。

第一个是长期停留在0.0.x。这类项目在发布时确实零风险，因为任何一次都可以是破坏性变更，相当于完全没有承诺。但它给用户传达的信号是“这个项目还没有任何可以依赖的东西”。如果项目和用户都有一定使用量了，还是尽快进入0.1.0甚至1.0.0，把承诺立起来。

第二个是频繁升主版本号。我见过一个库，一个月内从1.x升到5.x，每次升主版本号只是因为内部数据结构改了，完全不考虑外部兼容。这种情况下版本号的信号作用几乎为零，依赖方干脆选择永远锁在旧版本，项目声量也会很受影响。主版本号的升级应该谨慎、克制，是真正大事件时才动用的工具。

4.3 变更日志与版本号的对应关系

版本号必须和 changelog 强绑定。维护一个清晰的CHANGELOG.md，按照“主版本号.次版本号.修订号”分段记录，是 SemVer 落地的最重要配套动作。

推荐写法是“每个发布一个 H2 段落，段内列 Added / Changed / Deprecated / Removed / Fixed / Security 几个小类”。不要只写“更新依赖”这种废话，要写清开发者视角的可见变化。

实际维护中容易忽略的是：预发布版本的 changelog 如何处理。我一般只对正式发布版本写入清晰的变更记录，预发布版本可以合并到正式版本的记录里，或者单独标记为 unreleased 区块。重点是正式版本发布时，用户能只看 changelog 就判断升级风险和收益。

4.4 语言生态里的自动版本管理工具

很多语言生态提供了版本管理的工具或约定，但它们在 SemVer 基础上做了延伸。例如 Rust 的 Cargo 和 Python 的 setuptools 都支持基于 Git 提交信息或标签自动生成版本号。Git 标签v1.2.3配合 CI 自动发布，是很多开源项目的主流模式。

如果团队项目已经上了 CI，建议把“版本号 == git tag”作为一个硬性约定。发布脚本只允许从 tag 构建，不允许手动在提交里改版本号。这样每个版本号都对应一个明确的 git 历史节点，追溯成本极低。我经历过因为手工在源码里改版本号导致产出的包和 tag 对不上，排了很长时间的查错，后来全部改成 tag 触发流水线才消停。

5. 团队协作中的版本规范落地

5.1 把规则写进贡献指南

SemVer 规范如果只靠“负责人心里有数”，根本执行不下去。正确做法是把规则写进项目的CONTRIBUTING.md或文档站点：告诉提交 PR 的人，什么样的 MR 对应什么版本号升级，需要附带什么变更记录。

我常用的一段模板是：

• 如果修复的是不影响现有功能的 bug → 合并后由维护者提升修订号
• 如果新增了向后兼容的功能 → 合并后提升次版本号
• 如果删除了公开 API 或改变既有行为 → 必须先讨论，确认后提升主版本号
• 所有合并的 MR 必须补充 CHANGELOG 条目

这套规则不需要多复杂，但执行起来必须有维护者把关。如果放任开发者在合并时自己想升什么就升什么，版本号很快就失真了。

5.2 用工具约束而不是口头约束

比文档更有效的方式是引入工具约束。很多生态里都有检查 commit message 和版本号变更的 lint 工具。比如在用 Conventional Commits 的项目中，feat对应次版本号，fix对应修订号，BREAKING CHANGE对应主版本号。这些约定可以直接接入 CI 校验，不满足规则就不允许合入。

我见过的一些团队甚至会把“版本号决策”完全自动化：根据合并到主干分支的 commit 类型，由 CI 自动决定下一次发布是 minor 还是 patch，主版本号则要求在合并破坏性变更时必须在 PR 描述里显式填写。这套做法一旦跑起来，版本维护的认知负担会大幅下降。

工具也不限于 commit lint。发布流水线里可以加检查：本次发布相对上次 tag 的 diff 里如果出现了某个文件的删除，而提交信息里没有标BREAKING CHANGE，直接拦住。这种硬性规则虽然有时会误报，但整体收益大于成本。

5.3 处理好“内部模块”和“公共库”的差别

如果你的项目是一个被多个团队内部依赖的基础库，SemVer 同样适用，但沟通方式可以更直接。内部库不需要非得走完整的版本发布流程，但版本号和 changelog 依然要严谨。

如果项目只是某个应用内的私有模块，不对外发布，版本号的压力会小很多。但我还是建议保留 SemVer 的习惯，因为几个月后你自己回头看时，能通过版本号快速判断“这个模块什么时候引入了新能力、什么时候修了当时的 bug”，减少考古成本。

6. 常见问题速查表

下面整理了一些我经常在各项目里遇到的 SemVer 问题，每个问题都配有直接的判断依据和处理建议，供排查时快速对照。

这个表不是万能的，但覆盖了大部分日常边界情况。把它打印出来贴在工位上，发布前对照一遍，基本能避免因为版本号误判导致的翻车事故。

实战里我还有一个个人习惯：每天晚上或每次发布前，会跑一下“发布自检脚本”。脚本读取上次 release 到本次代码库所有出现过的feat:、fix:、BREAKING CHANGE标记，自动算出一个建议版本号，再和我要发布的版本号比对。不一致时，脚本会输出警告但不会强制阻止。这东西不复杂，十几行代码就能实现，但对维护多个库的时候非常有价值。

7. 版本号之外：发布纪律与工程素养

版本号是发布纪律的一部分，但它不是孤立的。真正让 SemVer 发挥作用的前提，是项目本身有一套清晰的发布流程。至少要做到：代码变更和版本发布分离、产物可复现、变更记录可追溯。否则即便版本号严格遵守规范，依赖方拿到也无法验证这个版本是否安全可用。

我个人的一个原则是：每一次发布的版本号都应当可以对应到 git 历史中的唯一提交。如果发现某个版本的代码无法从当前仓库构建出来，说明发布流程已经有问题。这种情况在缺乏 tag 管理的项目里很常见，也是 SemVer 最容易被架空的地方。

另一个容易被忽略的点是：对“破坏性变更”的定义要和依赖方对齐。维护者觉得“返回 null 改抛异常不算 API 变化”，依赖方可能觉得这就是破坏。跨团队沟通时提前定义清楚边界，比出了问题互相指责更有效。

我不知道你们团队现在对版本号的态度是什么，但我的感受是：版本号不是工程师用来交差的数字，而是你对依赖方的一纸信用承诺。数字本身没有魔力，魔力在于使用这些数字的人是否愿意遵守背后的规则。

用了这么多年 SemVer，我的体会是：它不是一个能解决所有依赖问题的银弹，但它是所有“可预期升级”的基石。把版本号规则讲清楚、执行好，带来的收益是长期的，而且越到项目后期感受越明显。