NPM 版本管理

为了保持 JavaScript 生态系统的健康、可靠和安全，每次对 npm 包进行更新时，建议遵循语义版本控制规范更新 package.json 文件中的版本号。遵循语义版本控制规范有助于依赖该 npm 包的开发人员了解给定版本的更改程度，并在必要时调整自己的代码。

1. 版本更新规则

建议从 1.0.0 开始，按照以下规则更新：

2. 预发布版本

预发布（pre-release）的版本可以通过在补丁版本后用连字符 - 连接点号 . 分隔的标志符表示。

标志符的合法字符集包含英文字母数字和连字符 [0-9A-Za-z-]。预发布版本表明该版本不稳定，可能无法满足其对应正常版本所表示的预期兼容性要求。命名例子如： 1.0.0-alpha，1.0.0-alpha.1， 1.0.0-0.3.7，1.0.0-x.7.z.92，1.0.0-x-y-z.–。

另外构建元数据（build metadata）跟在补丁版本或预发布版本后面，用加号 + 连接点号 . 分隔的标志符表示。标志符的合法字符集同上。命名例子如：1.0.0-alpha+001，1.0.0+20130313144700，1.0.0-beta+exp.sha.5114f85，1.0.0+21AF26D3—-117B344092BD。

3. 优先级

优先级指的是版本之间如何排序：

1. 按顺序将版本分为主要、次要、补丁和预发布标识符来计算优先级（构建元数据不考虑优先级）。

2. 从左到右比较这些标识符，优先级由第一个差异确定，如下所示： 主要、次要和补丁版本始终以数字进行比较。

   例如：1.0.0 < 2.0.0 < 2.1.0 < 2.1.1。

3. 当主要、次要和补丁版本相等时，预发布版本的优先级低于普通版本：

   例如：1.0.0-alpha < 1.0.0。

4. 对于具有相同主要、次要和补丁版本的两个预发布版本的优先级，必须通过从左到右比较每个点号分隔的标识符来确定，直到发现差异如下：

   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.

4. 版本匹配

基本的运算符：<、<=、>、>= 和 = （默认运算符）。

高级的范围选择：

• Hyphen Ranges X.Y.Z - A.B.C

  • 1.2.3 - 2.3.4 := >=1.2.3 <=2.3.4

  • 1.2 - 2.3.4 := >=1.2.0 <=2.3.4
  • 1.2.3 - 2.3 := >=1.2.3 <2.4.0-0
  • 1.2.3 - 2 := >=1.2.3 <3.0.0-0

• X-Ranges 1.2.x 1.X 1.2.* *（用 X、x或 * 在主版本、次版本和补丁版本占位）

  • * := >=0.0.0（不包括 prerelease，除非指定 includePrerelease）
  • 1.x := >=1.0.0 <2.0.0-0（匹配主版本）
  • 1.2.x := >=1.2.0 <1.3.0-0（匹配主版本和次版本）
  • ""（空字符） := * := >=0.0.0
  • 1 := 1.x.x := >=1.0.0 <2.0.0-0
  • 1.2 := 1.2.x := >=1.2.0 <1.3.0-0

• Tilde Ranges ~1.2.3 ~1.2 ~1（若指定了次版本，则允许补丁版本变化；否则允许次版本变化）

  • ~1.2.3 := >=1.2.3 <1.(2+1).0 := >=1.2.3 <1.3.0-0
  • ~1.2 := >=1.2.0 <1.(2+1).0 := >=1.2.0 <1.3.0-0（与 1.2.x 等价）
  • ~1 := >=1.0.0 <(1+1).0.0 := >=1.0.0 <2.0.0-0（与 1.x 等价）
  • ~0.2.3 := >=0.2.3 <0.(2+1).0 := >=0.2.3 <0.3.0-0
  • ~0.2 := >=0.2.0 <0.(2+1).0 := >=0.2.0 <0.3.0-0（与 0.2.x 等价）
  • ~0 := >=0.0.0 <(0+1).0.0 := >=0.0.0 <1.0.0-0（与 0.x 等价）
  • ~1.2.3-beta.2 := >=1.2.3-beta.2 <1.3.0-0（注意 1.2.3-beta.4 可以匹配，但 1.2.4-beta.2 不能匹配，因为主要、次要和补丁版本不一样）

• Caret Ranges ^1.2.3 ^0.2.3 ^0.0.3（不改变 [主要、次要、补丁版本] 最左非零元素的版本都可以匹配）

  • ^1.2.3 := >=1.2.3 <2.0.0-0
  • ^0.2.3 := >=0.2.3 <0.3.0-0
  • ^0.0.3 := >=0.0.3 <0.0.4-0
  • ^1.2.3-beta.2 := >=1.2.3-beta.2 <2.0.0-0
  • ^0.0.3-beta := >=0.0.3-beta <0.0.4-0
  • ^1.2.x := >=1.2.0 <2.0.0-0
  • ^0.0.x := >=0.0.0 <0.1.0-0
  • ^0.0 := >=0.0.0 <0.1.0-0
  • ^1.x := >=1.0.0 <2.0.0-0
  • ^0.x := >=0.0.0 <1.0.0-0

匹配的工具：npm semantic version calculator

5. npm version 命令

用法如下：

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]

• <newversion>：升到指定的版本
• major：升级主版本号
• minor：升级次版本号
• patch：升级补丁版本号
• premajor：升到下一主版本的预发布版本
• preminor：升到下一次版本的预发布版本
• prepatch：升到下一补丁版本的预发布版本
• prerelease：如果当前版本是非预发布版本，则和执行 prepatch 的效果一样，升到下一补丁版本的预发布版本。否则递增预发布版本。
• from-git：尝试读取最新的 git tag 来用作新版本号

例子：

preid 代表 prerelease identifier，用来给预发布版本添加前缀，如 v2.0.2-alpha.1 中的 alpha。

参考链接

• About semantic versioning | npm Docs
• npm semantic version calculator
• GitHub - npm/node-semver: The semver parser for node (the one npm uses)