语义化版本控制

语义化版本控制

语义化版本控制（Semantic Versioning，简称 SemVer）是一种版本号命名规范，旨在让开发者通过版本号快速理解项目的变更程度。它由三个数字组成：主版本号（major）、次版本号（minor）和修订号（patch），格式为 MAJOR.MINOR.PATCH。每个数字的变化代表不同类型的更新。

版本号结构

语义化版本号遵循 MAJOR.MINOR.PATCH 的格式，例如 1.2.3。每个部分的含义如下：

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

此外，版本号还可以包含预发布标签和构建元数据，例如 1.0.0-alpha.1 或 1.0.0+build.20240501。

版本号变更规则

主版本号变更

主版本号的变更表示项目发生了不兼容的 API 变更。例如：

• 从 1.2.3 升级到 2.0.0，表示移除了某些 API 或修改了现有 API 的行为。
• 如果项目依赖的库从 1.x.x 升级到 2.x.x，可能需要修改代码以适应新版本。

// 假设一个库的旧版本（1.x.x）导出一个函数：
module.exports = function add(a, b) {
  return a + b;
};

// 新版本（2.x.x）可能修改了函数签名：
module.exports = function add(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
};

次版本号变更

次版本号的变更表示新增了向后兼容的功能。例如：

• 从 1.2.3 升级到 1.3.0，表示新增了功能，但未破坏现有 API。
• 依赖库的次版本号升级通常不会导致代码报错。

// 旧版本（1.2.x）可能只支持加法：
module.exports = {
  add: (a, b) => a + b,
};

// 新版本（1.3.0）新增了乘法功能：
module.exports = {
  add: (a, b) => a + b,
  multiply: (a, b) => a * b, // 新增功能
};

修订号变更

修订号的变更表示修复了向后兼容的 bug。例如：

• 从 1.2.3 升级到 1.2.4，表示修复了某些问题，但未新增功能或破坏兼容性。
• 这类更新通常是安全的，可以直接应用。

// 旧版本（1.2.3）可能存在一个 bug：
module.exports = function subtract(a, b) {
  return a - b; // 如果 b > a，结果为负数
};

// 新版本（1.2.4）修复了逻辑：
module.exports = function subtract(a, b) {
  return Math.abs(a - b); // 修复：始终返回正数
};

预发布版本

预发布版本用于标记尚未稳定的版本，通常在版本号后追加 -alpha、-beta 或 -rc（Release Candidate）等标签。例如：

• 1.0.0-alpha.1：第一个 alpha 测试版。
• 1.0.0-beta.2：第二个 beta 测试版。
• 1.0.0-rc.1：第一个候选发布版。

预发布版本通常不推荐用于生产环境，但可以用于测试新功能。

{
  "dependencies": {
    "example-library": "1.0.0-beta.1"
  }
}

版本范围语法

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

• ^1.2.3：允许主版本号不变，次版本号和修订号可以更新（即 1.x.x）。
• ~1.2.3：允许主版本号和次版本号不变，修订号可以更新（即 1.2.x）。
• >=1.2.3：允许大于或等于 1.2.3 的版本。
• 1.2.3 - 2.0.0：允许从 1.2.3 到 2.0.0 之间的版本。

{
  "dependencies": {
    "lodash": "^4.17.21", // 允许 4.x.x
    "express": "~4.18.2", // 允许 4.18.x
    "react": ">=18.0.0"  // 允许 18.0.0 及以上
  }
}

实际应用示例

发布一个新版本

假设有一个 Node.js 项目，当前版本为 1.2.3。根据变更类型，可以按以下规则升级版本：

1. 修复了一个 bug：
   • 升级到 1.2.4。
2. 新增了一个功能：
   • 升级到 1.3.0。
3. 修改了 API 导致不兼容：
   • 升级到 2.0.0。

使用 npm version 命令可以快速更新版本：

# 修复 bug，更新修订号
npm version patch # 从 1.2.3 升级到 1.2.4

# 新增功能，更新次版本号
npm version minor # 从 1.2.4 升级到 1.3.0

# 不兼容变更，更新主版本号
npm version major # 从 1.3.0 升级到 2.0.0

依赖版本冲突

在团队协作中，依赖版本冲突是常见问题。例如：

• 项目 A 依赖 library@^1.2.0。
• 项目 B 依赖 library@^1.3.0。

如果 library 的最新版本是 1.4.0，npm 会尝试安装 1.4.0 以满足两者的需求。但如果项目 A 需要 library@~1.2.0，而项目 B 需要 library@^2.0.0，则可能无法自动解决冲突。

{
  "dependencies": {
    "library": "^1.2.0" // 项目 A 的依赖
  },
  "devDependencies": {
    "library": "^2.0.0" // 项目 B 的依赖
  }
}

工具支持

npm 的版本管理

npm 提供了多种命令和配置来管理版本：

• npm outdated：检查过时的依赖。
• npm update：更新依赖到允许的最新版本。
• npm install <package>@<version>：安装指定版本的包。

# 检查过时的依赖
npm outdated

# 更新所有依赖
npm update

# 安装特定版本
npm install lodash@4.17.21

版本锁定文件

package-lock.json 或 yarn.lock 文件用于锁定依赖的具体版本，确保不同环境安装的依赖一致。例如：

{
  "name": "example-project",
  "version": "1.0.0",
  "lockfileVersion": 2,
  "requires": true,
  "dependencies": {
    "lodash": {
      "version": "4.17.21",
      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
      "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg=="
    }
  }
}