npm 语义化版本 (SemVer) 符号指南

在 package.json 中，版本号遵循 语义化版本 (SemVer) 规范。理解这些符号对于管理项目依赖的稳定性至关重要。

1. 版本号结构

标准版本号格式为：主版本号.次版本号.补丁版本号 (Major.Minor.Patch)

例：1.2.3

• 主版本 (Major): 1 —— 做了不兼容的 API 修改（破坏性更新）。
• 次版本 (Minor): 2 —— 做了向下兼容的功能性新增。
• 补丁版本 (Patch): 3 —— 做了向下兼容的问题修正 (Bug Fix)。

2. 常用符号详解

2.1 插入符号 ^ (Caret) —— [推荐 / 默认]

含义：锁定主版本（左边第一个非零数字），允许更新次版本和补丁。 口诀：“主版本不变，其他更到最新。”

• 写法："^1.2.3"
• 允许范围：>= 1.2.3 且 < 2.0.0
• 示例：
  • ✅ 1.2.4 (修复 Bug)
  • ✅ 1.9.0 (新功能)
  • ❌ 2.0.0 (破坏性更新)
• 适用场景：绝大多数项目的默认选择，兼顾新功能获取与系统稳定性。

2.2 波浪号 ~ (Tilde) —— [保守]

含义：锁定主版本和次版本，只允许更新补丁。 口诀：“前两位不变，只修 Bug。”

• 写法："~1.2.3"
• 允许范围：>= 1.2.3 且 < 1.3.0
• 示例：
  • ✅ 1.2.4
  • ✅ 1.2.9
  • ❌ 1.3.0 (不接受新功能)
• 适用场景：对稳定性极度敏感，不希望引入任何新功能代码，只想接收安全修复时。

2.3 无符号 (Exact) —— [锁死]

含义：必须完全匹配指定版本。 口诀：“就是这个版本，改一个数都不行。”

• 写法："1.2.3"
• 允许范围：仅 1.2.3
• 示例：
  • ❌ 1.2.4
• 适用场景：关键基础设施，或者确信升级会挂掉的情况。通常配合 package-lock.json 使用。

2.4 星号 * 或 x (Wildcard) —— [危险]

含义：安装最新发布的任意版本。

• 写法："*" 或 "1.x"
• 允许范围：任意版本。
• 适用场景：不推荐在生产环境使用。仅用于实验性项目或临时安装工具。

3. 高级用法

3.1 比较操作符

用于指定明确的数学范围。

• > 1.2.3：必须大于此版本。
• >= 1.2.3：大于或等于。
• <= 1.2.3：小于或等于。
• < 2.0.0：小于。

3.2 逻辑或 ||

用于同时支持多个不连续的版本范围（常见于库的开发）。

• 写法："^1.2.3 || ^2.0.0"
• 含义：可以使用 1.x 的最新版，或者 2.x 的最新版。

4. 特殊情况：0.x.x 版本

当主版本号为 0 时（如 0.2.3），表示软件处于初始开发阶段，API 可能随时变动。此时 ^ 的行为会变严格。

• 写法："^0.2.3"
• 行为：不会升级到 0.3.0，只会升级到 0.2.4。
• 原因：在 0.x 阶段，中间数字（Minor）的改变通常意味着破坏性更新。

5. 总结速查表