语义化版本控制

语义化版本控制的概念

语义化版本控制（Semantic Versioning，简称 SemVer）是一种版本号命名规范，旨在让开发者通过版本号就能理解代码变更的影响范围。它由三个数字组成，格式为MAJOR.MINOR.PATCH，分别代表主版本号、次版本号和修订号。这种规范在 Node.js 生态中广泛应用，尤其是在 npm 包管理中。

版本号的组成

语义化版本号的三个部分分别表示不同的变更类型：

1. MAJOR（主版本号）：当进行不兼容的 API 变更时递增。
2. MINOR（次版本号）：当新增向后兼容的功能时递增。
3. PATCH（修订号）：当修复向后兼容的 bug 时递增。

例如，1.2.3表示主版本号为 1，次版本号为 2，修订号为 3。

版本号的递增规则

MAJOR 版本递增

当代码的变更破坏了现有 API 的兼容性时，需要递增 MAJOR 版本。例如：

• 移除某个函数或方法。
• 修改函数参数的数量或顺序。
• 修改函数的返回值类型。

// v1.0.0
function add(a, b) {
  return a + b;
}

// v2.0.0（不兼容变更：参数顺序改变）
function add(b, a) {
  return a + b;
}

MINOR 版本递增

当新增功能但不破坏现有 API 时，递增 MINOR 版本。例如：

• 新增一个函数或方法。
• 为现有函数添加可选参数。

// v1.0.0
function add(a, b) {
  return a + b;
}

// v1.1.0（新增功能：支持第三个可选参数）
function add(a, b, c = 0) {
  return a + b + c;
}

PATCH 版本递增

当修复 bug 且不引入新功能时，递增 PATCH 版本。例如：

• 修复函数中的逻辑错误。
• 修复性能问题。

// v1.0.0（有 bug 的版本）
function add(a, b) {
  return a - b; // 错误：应该是加法
}

// v1.0.1（修复 bug）
function add(a, b) {
  return a + b;
}

预发布版本和构建元数据

除了标准的MAJOR.MINOR.PATCH格式外，语义化版本还支持预发布版本和构建元数据：

• 预发布版本：在版本号后追加-和标识符，例如1.0.0-alpha、1.0.0-beta.1。
• 构建元数据：在版本号后追加+和标识符，例如1.0.0+20230301。

// package.json 示例
{
  "version": "1.0.0-alpha",
  "dependencies": {
    "lodash": "^4.17.21"
  }
}

版本范围语法

在 Node.js 的package.json中，依赖的版本范围可以通过以下符号指定：

• ^：允许 MINOR 和 PATCH 版本更新，例如^1.2.3允许1.2.3到2.0.0以下的版本。
• ~：仅允许 PATCH 版本更新，例如~1.2.3允许1.2.3到1.3.0以下的版本。
• >、<、>=、<=：指定版本范围，例如>=1.2.3 <2.0.0。
• *：匹配任何版本，例如1.x匹配1.0.0到2.0.0以下的版本。

// package.json 示例
{
  "dependencies": {
    "react": "^17.0.2", // 允许 17.0.2 到 18.0.0 以下的版本
    "lodash": "~4.17.21" // 允许 4.17.21 到 4.18.0 以下的版本
  }
}

语义化版本的实际应用

发布新版本

在 Node.js 项目中，可以通过npm version命令自动更新版本号：

# 递增 PATCH 版本
npm version patch

# 递增 MINOR 版本
npm version minor

# 递增 MAJOR 版本
npm version major

版本锁定

为了避免依赖版本不一致导致的问题，可以使用package-lock.json或yarn.lock锁定依赖版本：

# 生成 package-lock.json
npm install

# 使用 yarn 生成 yarn.lock
yarn install

常见问题与解决

版本冲突

当多个依赖包对同一包的版本要求冲突时，可能会导致安装失败。可以通过以下方式解决：

1. 更新冲突的依赖包到兼容版本。
2. 使用resolutions字段（yarn）或overrides字段（npm）强制指定版本。

// package.json（yarn 的 resolutions 示例）
{
  "resolutions": {
    "lodash": "4.17.21"
  }
}

预发布版本的使用

预发布版本默认不会被安装，除非显式指定：

# 安装预发布版本
npm install package@next

语义化版本的工具支持

版本检查工具

可以使用semver库来比较和验证版本号：

const semver = require('semver');

console.log(semver.valid('1.2.3')); // '1.2.3'
console.log(semver.gt('1.2.3', '1.2.2')); // true
console.log(semver.satisfies('1.2.3', '^1.2.0')); // true

自动化版本管理

可以使用standard-version或release-it等工具自动化版本管理和发布流程：

# 安装 standard-version
npm install --save-dev standard-version

# 在 package.json 中添加脚本
{
  "scripts": {
    "release": "standard-version"
  }
}

语义化版本的最佳实践

1. 从 1.0.0 开始：初始开发阶段可以使用0.x.x，但正式发布应从1.0.0开始。
2. 及时更新版本号：每次发布代码变更时都应更新版本号。
3. 使用版本范围：在package.json中合理使用^或~以避免过于严格的版本锁定。
4. 记录变更：通过CHANGELOG.md记录每个版本的变更内容。