语义化版本号升级

Q: 预发布版本怎么比较大小？

2.0.0-alpha < 2.0.0-alpha.1 < 2.0.0-beta < 2.0.0-rc.1 < 2.0.0，包管理器按此规则解析。

Q: 修复安全漏洞该升哪段？

按修复方式定级，不按严重程度：打补丁不改接口 → PATCH（绝大多数情况）；修复必须改 API（如强制加鉴权参数）→ MAJOR。安全修复要尽快让用户能升，所以社区惯例是尽一切可能保持 PATCH 兼容，把破坏性改动拆到后续大版本。

Q: 多个变更同时发布怎么定级？

取最高级别：一次发布含 feat 和 fix → MINOR；含任何破坏性变更 → MAJOR。不要为了「升得好看」把破坏性变更拆到多次发布，那只会让用户反复适配。

Q: MAJOR 升位后还要维护旧版本吗？

看用户量和资源：主流库通常给上一个 MAJOR 版本 6-12 个月的安全修复期（LTS），文档注明支持时间表。小库至少在 MAJOR 发布说明里写清旧版停止维护的时间点，让用户有迁移预期。

Q: 0.x 项目什么时候该发 1.0.0？

Semver 官方定义：API 稳定、被生产环境依赖时就该 1.0.0。长期停在 0.x 的问题：用户无法区分你的破坏性变更（0.3 → 0.4 可能 breaking），依赖管理工具也无法正确锁定。如果接口已经三个月没变过，就勇敢发 1.0.0。

Q: 预发布版本能被 semver 范围匹配到吗？

不能自动匹配：^1.2.3 不会装 1.3.0-beta.1，必须显式指定。这是保护机制——预发布版默认只给愿意尝鲜的用户。npm 的 dist-tag（latest/next）就是配合这个机制分发。

Q: 构建元数据（+build）有什么用？

加号后缀（1.2.3+build.456）被 Semver 忽略，不参与版本比较，用于记录构建号、commit 哈希等追溯信息。包管理器会把 1.2.3+a 和 1.2.3+b 视为同一版本，所以别用它区分发布。

Q: Monorepo 里多个包版本怎么管？

两种流派：固定模式（所有包同版本，如 Babel、Angular——发版简单但常为无变更包发新版）和独立模式（各包按自身变更定级，如 Lerna independent——精准但版本矩阵复杂）。小团队推荐固定模式，包间相互依赖多时尤其省心。

Q: changelog 和版本号怎么联动？

Keep a Changelog 规范：按版本号分节、按 Added/Changed/Deprecated/Removed/Fixed/Security 分类。发版流程：开发期在 Unreleased 节累积条目 → 发版时改为版本号+日期 → 工具（changesets、semantic-release）可自动从提交信息生成。版本号语义化的前提是 CHANGELOG 先语义化。

什么是语义化版本号升级？

语义化版本（Semantic Versioning）格式为 MAJOR.MINOR.PATCH：不兼容的 API 变更升 MAJOR，向下兼容的新功能升 MINOR，向下兼容的修复升 PATCH。

0.x.y 是特殊阶段：主版本 0 表示 API 随时可变，1.0.0 是公开 API 稳定的承诺线。很多库长期停在 0.x 就是不想做稳定承诺。

预发布版本用连字符追加：2.0.0-alpha、2.0.0-beta.1、2.0.0-rc.2，优先级低于同号正式版；构建元数据用加号：2.0.0+build.42。

语义化版本（Semver）的 MAJOR.MINOR.PATCH 三段各自承担明确承诺：PATCH 修 bug 不改接口、MINOR 加功能向后兼容、MAJOR 有破坏性变更。「这次发版该升哪一段」是发布流程的固定决策点，升错了会向用户传递错误的兼容性信号。

判定核心是「用户升级后需要改代码吗」：不需要改任何东西 → PATCH；需要适配新功能但旧代码照常 → MINOR；旧代码会编译失败或行为改变 → MAJOR。拿不准时往高升，低估破坏性的代价比高估大得多。

工程实践中，版本号应该由提交历史驱动而非拍脑袋：Conventional Commits 规范用 feat:/fix:/BREAKING CHANGE: 前缀标记提交类型，配合工具（semantic-release）可自动汇总得出下一段位。手工管理时，发版前回顾 CHANGELOG 逐条归类是最可靠的做法。

破坏性变更 → MAJOR+1、其余归零；新功能 → MINOR+1、PATCH 归零；修复 → PATCH+1

版本升级规则：MAJOR 升位则 MINOR、PATCH 归零（2.4.7 → 3.0.0）；MINOR 升位则 PATCH 归零（2.4.7 → 2.5.0）；PATCH 升位其余不变（2.4.7 → 2.4.8）。预发布版本追加后缀：2.5.0 → 2.5.0-alpha.1 → 2.5.0-beta.2 → 2.5.0-rc.1 → 2.5.0 正式。0.x 阶段特殊：0.MINOR 视为破坏性、0.PATCH 视为新增（0.x 无兼容性承诺）。

变更类型与版本升位对照
变更内容	升位	示例（2.4.7 →）	用户影响
修复 bug，不改接口	PATCH	2.4.8	无感升级
新增可选参数/新 API	MINOR	2.5.0	旧代码照常，可用新功能
删除/改名公开 API	MAJOR	3.0.0	旧代码报错，需修改
修改 API 返回结构	MAJOR	3.0.0	解析逻辑需适配
仅文档/注释/内部重构	PATCH 或不发版	2.4.8	无行为变化
提升最低运行时版本	MAJOR	3.0.0	环境需先升级

如何使用语义化版本号升级

1
输入当前版本号。
2
选择变更类型。
3
复制下一版本号。

计算示例

例 1新增功能

当前 1.4.2，本次新增导出接口（向下兼容）：下一版本 1.5.0，PATCH 归零。

例 2破坏性变更

当前 1.4.2，本次删除了废弃参数：下一版本 2.0.0——主版本升级是在向所有下游使用者发「适配通知」。

例 3常规功能迭代

当前 4.2.1，本次合并了 3 个 feat 提交（新增导出 CSV、暗色模式、快捷键设置）和 5 个 fix 提交。按规则取最高变更级别：feat → MINOR，得 4.3.0。fix 被 MINOR 升位吸收（PATCH 归零），不需要单独发 4.2.2。

例 4破坏性升级

当前 4.3.0，计划把 fetchData() 的回调风格改为 Promise，并删除已废弃两年的旧参数。两个变更都破坏兼容 → MAJOR，得 5.0.0。同步发布迁移指南，并在 5.0.0 前先发 4.4.0 对旧用法加 deprecation 警告，给用户缓冲期。

例 5预发布流转

5.0.0 开发中，需要社区试用：先发 5.0.0-alpha.1（内部联调）→ 5.0.0-beta.1（功能冻结，修 bug）→ 5.0.0-rc.1（候选，只修致命问题）→ 5.0.0。每阶段升预发布号，正式版号不变；npm 用户需显式 npm install pkg@next 才会装到预发布版。

注意事项

「修复 bug 导致行为变化」如果下游可能依赖了错误行为，也应升 MAJOR（Hyrum 定律）。
依赖范围写法：^1.4.2 允许升级到 2.0.0 以下，~1.4.2 只允许 PATCH 升级。
内部重构不影响 API 的行为变化升 PATCH 即可。
「内部重构算不算 PATCH」看是否改变可观察行为：纯代码搬移不发版或 PATCH，性能显著变化建议至少 MINOR 并在 CHANGELOG 说明。
依赖升级本身也算变更：升级了一个会改变输出格式的依赖，等同于自身行为变更，按影响定级。
0.x 阶段的兼容性承诺弱，但用户习惯已形成——1.0.0 前的破坏性变更也要在 CHANGELOG 显著标注。

常见问题

不影响代码行为的纯文档修改可以不发版，或随下一个 PATCH 一起发布。