语义化版本
Semantic Versioning
中级通用语义化版本（Semantic Versioning）是一种用主版本号、次版本号和修订号表达软件兼容性变化的编号方式。它帮你和使用者判断升级可能带来的影响：修复问题、增加兼容功能和破坏旧用法，对应不同级别的版本变化。
你可能会说：「这个接口改了之后，我想让版本号能告诉接入方：升级会不会弄坏他们现有的代码。」
读之前建议先了解
动手看看检查插件升级范围
哪些已发布版本会被安装
产品依赖的插件写着 ^1.4.0：它允许安装 1.4.x 和 1.5.0，但不包括 2.0.0。修订号通常对应修复，次版本号对应兼容的新功能，主版本号可能带来不兼容变化。
试试把范围改成 ~1.4.0，看看 1.5.0 为什么不再被选中：这个范围只接受 1.4 系列的后续修订版本。
再把范围改成 ^1.4.2，看看 1.4.0 为什么被排除：即使主、次版本号相同，低于指定修订号的版本也不满足范围。
要点版本号的三段数字分别告诉你什么？
- 1
先约定什么算对外承诺
判断该改哪段数字，先看你承诺给使用者的接口是什么。做一个供别的团队调用的服务时，端点、请求字段和响应格式可能都在其中；只改内部实现，通常不算改变对外用法。
- 2
三段数字对应三类变化
以 2.4.1 为例：修复问题且保持兼容，通常把末段加一；增加兼容的新功能，把中段加一；让旧用法失效，把首段加一。前一段增加时，后面的段数通常归零。
- 3
兼容要从使用者角度判断
你删除一个 API 响应字段，即使自己的页面已经改好，依赖该字段的客户程序仍可能出错，所以这是破坏性变化。反过来，改动代码很多，也不一定意味着要升主版本。
- 4
预发布版本另有标记
如果新功能还在邀请用户试用，可以在版本号后加预发布标记，例如 2.5.0-beta.1。这样别人能看出它还不是正式版；从 1.0.0 起使用三段数字时，兼容性承诺也更容易说清楚。
容易混淆的地方
语义化版本回答的是“这次改动会不会影响旧用法”，不是“代码存在哪里、何时上线”。Git 标签可以记录某次提交对应的版本，但标签名本身不保证编号符合语义化版本。部署上线则是把代码交给用户使用：你可以发布新版本却暂不部署，也可以把同一版本部署到多个环境。
什么时候用
适合用
- 你维护供其他团队调用的 API，需要让他们从版本变化判断升级前是否要改接入代码。
- 你发布可复用的组件或插件，使用者需要知道一次更新是修复、兼容功能增加，还是破坏旧用法。
- 你请 AI Agent 整理发布流程，希望它根据对外接口的变化建议版本号，并说明判断依据。
不适合用
- 你只是给内部任务排先后，没有要发布给人升级的软件；用产品待办列表或任务编号更直接。
- 你想控制新功能先给哪些用户看到；用功能开关或金丝雀发布，版本号不能替你控制开放范围。
- 你想定位某次代码改动是谁提交的；查 Git 提交记录和差异对比，比看版本号更合适。
练一练选一个答案，看看解释
你的团队发布一个供客户调用的 API。原来响应里的 customerName 字段被删除，改为返回 displayName；同时还修复了一个不影响接口的错误。当前版本是 2.3.4，下一正式版怎么编号更合适？
让 AI 帮你做复制给 AI Agent 直接用
请按语义化版本检查这次改动：先列出项目对使用者承诺的接口，再对比上一正式版，指出哪些改动保持兼容、哪些会让旧用法失效。根据影响建议下一个正式版本号，并解释理由；信息不足时列出需要我确认的接口约定。