版本号不只是发布流水号,它是对使用者的兼容性承诺:主版本号变了,意味着有不兼容的修改;次版本号变了,意味着只是向下兼容地加了功能;只有修订号变了,意味着只是一次向下兼容的修复。

本文按 SemVer 2.0.0 的规则梳理:版本号怎么组成、三个数字分别在什么时候递增、先行版本和构建元数据怎么用,以及优先级如何比较。

1. 版本号的格式

标准版本号必须是 X.Y.Z 的形式,X、Y、Z 都是非负整数,且数字前不允许补零。X 是主版本号,Y 是次版本号,Z 是修订号,每一段都按数值递增,所以 1.9.1 的下一个次版本是 1.10.0,而不是 1.9.2。

在 X.Y.Z 后面还可以接两段扩展信息:

1.4.2
1.4.2-beta.1
1.4.2+20261121
1.4.2-rc.1+build.5
  • 连字符 - 后面是先行版本号(pre-release),表示这个版本还不稳定。
  • 加号 + 后面是构建元数据(build metadata),只用于记录构建信息,不参与优先级比较。

2. 三个数字何时递增

递增位触发条件示例
主版本号 X公共 API 出现不兼容的修改2.3.1 → 3.0.0
次版本号 Y向下兼容地新增功能;公共 API 的功能被标记为弃用2.3.1 → 2.4.0
修订号 Z只做向下兼容的问题修正2.3.1 → 2.3.2

三个细节容易被忽略:

  • 次版本号递增时,修订号必须归零;主版本号递增时,次版本号和修订号都必须归零。
  • 主版本号为 0(0.y.z)表示软件还在初始开发阶段,公共 API 随时可能变化,不应被当作稳定版;1.0.0 用来界定公共 API 的形成。
  • 版本一旦发布,就禁止修改该版本的内容;任何改动都要以新版本发布。

3. 先行版本与构建元数据

3.1 先行版本

先行版本号用于标记尚未稳定的版本,优先级低于对应的正式版本。它由连字符引出,后面是一串以点分隔的标识符:

1.0.0-alpha
1.0.0-alpha.1
1.0.0-0.3.7
1.0.0-x.7.z.92

标识符只能由 ASCII 字母、数字和连字符组成,不能有空白;数字型标识符同样不允许前导零。

3.2 构建元数据

构建元数据由加号引出,同样是点分隔的标识符,用来记录这次构建的额外信息:

1.0.0+20130313144700
1.0.0-beta+exp.sha.5114f85
1.0.0+001

判断优先级时构建元数据会被忽略。两个版本如果只有构建元数据不同,它们属于同一优先级。

4. 优先级怎么比较

比较从主版本号开始,依次看主版本号、次版本号、修订号,都是按数值比较:

1.0.0 < 2.0.0 < 2.1.0 < 2.1.1

主版本号、次版本号、修订号都相同时,再看先行版本号:

  • 没有先行版本号的版本优先级更高,即 1.0.0-alpha < 1.0.0。
  • 两个都是先行版本时,从左到右逐个比较点分隔的标识符:纯数字按数值比,含字母或连字符的按 ASCII 顺序比,数字标识符的优先级低于非数字标识符;前面的标识符都相同时,字段更多的版本优先级更高。

完整的一组示例如下:

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-beta.11 < 1.0.0-rc.1 < 1.0.0

注意 beta.2 < beta.11 是按数值比较的结果,不是按字符串字典序。

5. 常见误区

  • v1.2.3 不是语义化版本号本身。 v 是 Git 标签的常见前缀,标签可以叫 v1.2.3,但版本号是 1.2.3。
  • 前导零不合法。 01.2.3、1.02.3 都不符合规范。
  • 1.2 这种两段式不是 SemVer。 三段缺一不可。
  • 只差构建元数据的版本优先级相同。 不要指望用 +build.1、+build.2 来区分先后。
  • 已发布的版本不能改。 如果误把不兼容的改动发成了次版本或修订版本,正确做法是发布一个新版本恢复兼容性,并尽量在文档里记录有问题的版本,而不是覆盖已发布的包。
  • 0.y.z 不是“可以随便标稳定”的阶段。 它明确表示公共 API 尚未稳定。

6. 在项目里落地

  • 在 README 中声明项目遵循语义化版本 2.0.0,并链接规范原文,让使用者知道版本号的含义。
  • 发布时用 Git 标签记录版本,标签名可以带 v 前缀,标签信息里写完整版本号:
git tag v1.2.3 -m "Release version 1.2.3"
  • 弃用公共 API 时,先在文档中标注,并通过一个新的次版本发布弃用信息;至少经过一个包含弃用说明的次版本,才能在下一个主版本中移除。
  • 声明依赖时可以直接利用这层承诺。例如依赖 3.1.0 及以上、4.0.0 以下的版本,就能在 3.1.1、3.2.0 发布后放心升级。

总结

  • 版本号固定为 X.Y.Z:不兼容改 X,向下兼容加功能改 Y,向下兼容修问题改 Z,进位时低位归零。
  • 先行版本表示不稳定,优先级低于正式版本;构建元数据只记录信息,不参与比较。
  • 版本号的价值在于承诺:一旦发布就不再修改,用新版本表达每一次变化。

参考资料