版本号不只是发布流水号,它是对使用者的兼容性承诺:主版本号变了,意味着有不兼容的修改;次版本号变了,意味着只是向下兼容地加了功能;只有修订号变了,意味着只是一次向下兼容的修复。
本文按 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,进位时低位归零。 - 先行版本表示不稳定,优先级低于正式版本;构建元数据只记录信息,不参与比较。
- 版本号的价值在于承诺:一旦发布就不再修改,用新版本表达每一次变化。
参考资料
- 语义化版本 2.0.0(简体中文):本文规则转述自该规范,原作者 Tom Preston-Werner,原文以 CC BY 3.0 许可发布。
- Semantic Versioning 2.0.0(英文原版)
- RFC 2119:规范中 MUST、SHOULD、MAY 等关键词的解读依据