软件版本控制规范

---

1. 摘要

版本格式：主版本号.次版本号.修订号，版本号递增规则如下：

• 主版本号：当你做了不兼容的 API 修改，
• 次版本号：当你做了向下兼容的功能性新增，
• 修订号：当你做了向下兼容的问题修正。

先行版本号及版本编译信息可以加到“主版本号.次版本号.修订号”的后面，作为延伸。

2. 语义化版本控制规范（Semver）

以下关键词 MUST、MUST NOT、REQUIRED、SHALL、SHALL NOT、SHOULD、SHOULD NOT、 RECOMMENDED、MAY、OPTIONAL 依照 RFC 2119 的叙述解读。

1. 标准的版本号必须（MUST）采用 X.Y.Z 的格式，其中 X、Y 和 Z 为非负的整数，且禁止（MUST NOT）在数字前方补零。X 是主版本号、Y 是次版本号、而 Z 为修订号。每个元素必须（MUST）以数值来递增。例如：1.9.1 -> 1.10.0 -> 1.11.0。
2. 标记版本号的软件发行后，禁止（MUST NOT）改变该版本软件的内容。任何修改都必须（MUST）以新版本发行。
3. 主版本号为零（0.y.z）的软件处于开发初始阶段，一切都可能随时被改变。这样的公共 API 不应该被视为稳定版。
4. 1.0.0 的版本号用于界定公共 API 的形成。这一版本之后所有的版本号更新都基于公共 API 及其修改内容。
5. 修订号 Z（x.y.Z | x > 0）必须（MUST）在只做了向下兼容的修正时才递增。这里的修正指的是针对不正确结果而进行的内部修改。
6. 次版本号 Y（x.Y.z | x > 0）必须（MUST）在有向下兼容的新功能出现时递增。在任何公共 API 的功能被标记为弃用时也必须（MUST）递增。也可以（MAY）在内部程序有大量新功能或改进被加入时递增，其中可以（MAY）包括修订级别的改变。每当次版本号递增时，修订号必须（MUST）归零。
7. 主版本号 X（X.y.z | X > 0）必须（MUST）在有任何不兼容的修改被加入公共 API 时递增。其中可以（MAY）包括次版本号及修订级别的改变。每当主版本号递增时，次版本号和修订号必须（MUST）归零。
8. 先行版本号可以（MAY）被标注在修订版之后，先加上一个连接号再加上一连串以句点分隔的标识符来修饰。标识符必须（MUST）由 ASCII 字母数字和连接号 [0-9A-Za-z-] 组成，且禁止（MUST NOT）留白。数字型的标识符禁止（MUST NOT）在前方补零。先行版的优先级低于相关联的标准版本。被标上先行版本号则表示这个版本并非稳定而且可能无法满足预期的兼容性需求。范例：1.0.0-alpha、1.0.0-alpha.1、1.0.0-0.3.7、1.0.0-x.7.z.92。
9. 版本编译信息可以（MAY）被标注在修订版或先行版本号之后，先加上一个加号再加上一连串以句点分隔的标识符来修饰。标识符必须（MUST）由 ASCII 字母数字和连接号 [0-9A-Za-z-] 组成，且禁止（MUST NOT）留白。当判断版本的优先层级时，版本编译信息可（SHOULD）被忽略。因此当两个版本只有在版本编译信息有差别时，属于相同的优先层级。范例：1.0.0-alpha+001、1.0.0+20130313144700、1.0.0-beta+exp.sha.5114f85。
10. 版本的优先层级指的是不同版本在排序时如何比较。
11. 判断优先层级时，必须（MUST）把版本依序拆分为主版本号、次版本号、修订号及先行版本号后进行比较（版本编译信息不在这份比较的列表中）。
12. 由左到右依序比较每个标识符，第一个差异值用来决定优先层级：主版本号、次版本号及修订号以数值比较。例如：1.0.0 < 2.0.0 < 2.1.0 < 2.1.1。
13. 当主版本号、次版本号及修订号都相同时，改以优先层级比较低的先行版本号决定。
14. 例如：1.0.0-alpha < 1.0.0。
15. 有相同主版本号、次版本号及修订号的两个先行版本号，其优先层级必须（MUST）透过由左到右的每个被句点分隔的标识符来比较，直到找到一个差异值后决定：
    1. 只有数字的标识符以数值高低比较。
    2. 有字母或连接号时则逐字以 ASCII 的排序来比较。
    3. 数字的标识符比非数字的标识符优先层级低。
    4. 若开头的标识符都相同时，栏位比较多的先行版本号优先层级比较高。
    例如：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。

3. 版本阶段说明

通常，npm 分为 先行版本 和 标准版本 两个大的阶段。

通过 npm view react versions 可以查看到 react 所有版本号

先行版本

先行版本 指未正式发布的版本 如 1.0.0-alpha.0、1.0.0-alpha.1、1.0.0-beta.0、1.0.0-rc.0等版本

alpha（内测版本）

alpha 是内部测试版，由于功能亦未完善，一般不向外发布，会有很多 Bug，除非你也是测试人员，否则不建议使用。alpha 是希腊字母的第一位，表示最初级的版本，alpha 是 α，beta 就是 β，alpha 版就是比 beta 还早的测试版。
所以，它是整个软件发布周期中的第一个阶段。

beta（灰度版本）

该版本相对于 α 版已有了很大的改进，消除了严重的错误，但还是存在着缺陷，需要经过多次测试来进一步消除。bate 版本最早对外公开的软件版本，会收集使用者的反馈意见，以便作为进一步修正软件的参考，这个阶段的版本会一直加入新的功能和特性。

rc（release candidate 候选版本）

candidate 是候选人的意思，用在软件上就是候选版本，release candidate 就是发行候选版本。和 beta 版最大的区别在于 beta 阶段会一直加入新的功能或特性，但是到了 rc 版本，几乎就不会加入新的功能了，而主要着重于除错。rc 版本是最终发放给用户的最接近正式版的版本，修复完已知 bug 后就是正式版了，也就是正式版之前的最后一个测试版。

标准版本

标准版本指正式发布的版本，如 1.0.0、1.0.1 等版本

release（最终版本）

该版本意味 “最终版本”，在前面版本的一系列测试版之后，终归会有一个正式版本，是最终交付用户使用的一个版本。该版本有时也称为标准版。一般情况下，release 不会以单词形式出现在软件封面上，取而代之是符号（R）。

4. 升级npm包版本

通常我们发布一个包到npm仓库时，我们的做法是先修改 package.json 为某个版本，然后执行 npm publish 命令。手动修改版本号的做法建立在你对 Semver 规范特别熟悉的基础之上，否则可能会造成版本混乱。npm 考虑到了这点，它提供了相关的命令来让我们更好的遵从 Semver 规范：

升级版本号

命令	作用	执行结果version
npm version prerelease	升级预发布号	首次执行1.0.0 -> 1.0.0-0再次执行1.0.0 -> 1.0.0-1
npm version prerelease --preid=alpha	升级预发布号alpha版本	1.0.0 -> 1.0.1-alpha.11.0.1-alpha.1 -> 1.0.1-alpha.2
npm version prerelease --preid=beta	升级预发布号beta版本	1.0.0 -> 1.0.1-beta.11.0.1-beta.1 -> 1.0.1-beta.2
npm version prepatch	升级修订号，保留预发布号	1.0.0-1 -> 1.0.1-1
npm version preminor	升级次版本号，保留预发布号	1.0.1-0 -> 1.1.0-0
npm version premajor	升级主版本号，保留预发布号	1.1.0-0 -> 2.0.0-0
npm version patch	升级修订号	首次执行2.0.0-0 -> 2.0.0再次执行2.0.0 -> 2.0.1
npm version minor	升级次版本号	2.0.1 -> 2.1.0
npm version major	升级主版本号	2.1.0 -> 3.0.0

发布

• 当执行 npm publish 时，会首先将当前版本发布到 npm registry，然后更新 dist-tags.latest 的值为新版本。
• 当执行 npm publish --tag=next 时，会首先将当前版本发布到 npm registry，并且更新 dist-tags.next 的值为新版本。这里的 next 可以是任意有意义的命名（比如：v1.x、v2.x 等等）OK，接下来用户就可以通过 npm install package@next 来指定安装 next 版本的依赖了。

5. 常见依赖版本符号

在 npm 的依赖的规则中，还有 ~、>、<、=、>=、<=、-、||、x、X、* 等符号。

当执行 npm install xxx -S 来安装三方包时，npm 会首先安装包的最新版本，然后将包名及版本号写入到 package.json 文件中。被安装的依赖的版本号前会默认加上 ^ 符号。

比如，通过 npm 安装 vue 时：

{"dependencies": {"vue": "^2.5.2"}}

• ^：表示同一主版本号中，不小于指定版本号的版本号（锁定主版本，可升级次版本号与修订号）

`^2.2.1` 对应主版本号为 2，不小于 `2.2.1` 的版本号，比如 `2.2.1`、`2.2.2`、`2.3.0`，主版本号固定
// 当该依赖有最新版本时(eg：2.3.3)，npm install 会安装最新的依赖

• ~：表示同一主版本号和次版本号中，不小于指定版本号的版本号（锁定主版本与次版本号，可升级修订号）

`~2.2.1` 对应主版本号为 2，次版本号为 2，不小于 `2.2.1` 的版本号，比如 `2.2.1、2.2.2`，主版本号和次版本号固定

• >、<、=、>=、<=、-：用来指定一个版本号范围

 `>2.1`
 `1.0.0 - 1.2.0`
// 注意使用 `-` 的时候，必须两边都有空格。

• ||：表示或

`^2 <2.2 ||> 2.3`

• x、X、*：表示通配符

`*` 对应所有版本号
`3.x` 对应所有主版本号为 3 的版本号

注意

在 package.json 文件中最常见的应该是 “yargs”: “^14.0.0” 这种格式的 依赖, 因为我们在使用 npm install package 安装包时，npm 默认安装当前最新版本，然后在所安装的版本号前加 ^ 号。

注意，当主版本号为 0 的情况，会被认为是一个不稳定版本，情况与上面不同：
主版本号和次版本号都为 0: ^0.0.z、~0.0.z 都被当作固定版本，安装依赖时均不会发生变化。
主版本号为 0: ^0.y.z 表现和 ~0.y.z 相同，只保持修订号为最新版本。

参考资料： Semver