语义化版本

概述

语义化版本（Semantic Versioning，SemVer）是一套版本号命名规范，它通过版本号传达代码变更的含义，帮助开发者理解版本之间的兼容性关系。

语义化版本规范

版本号格式

主版本号.次版本号.修订号
MAJOR.MINOR.PATCH

示例：

1.0.0
2.1.3
3.2.1

版本号递增规则

版本类型	递增条件	示例
MAJOR	不兼容的 API 变更	1.0.0 → 2.0.0
MINOR	向后兼容的功能新增	1.0.0 → 1.1.0
PATCH	向后兼容的问题修复	1.0.0 → 1.0.1

规则详解

主版本号（MAJOR）：

当进行不兼容的 API 变更时递增：

javascript

// v1.0.0
function greet(name) {
  return 'Hello, ' + name;
}

// v2.0.0 - 破坏性变更
function greet(firstName, lastName) {
  return 'Hello, ' + firstName + ' ' + lastName;
}

次版本号（MINOR）：

当添加向后兼容的新功能时递增：

javascript

// v1.0.0
function greet(name) {
  return 'Hello, ' + name;
}

// v1.1.0 - 新增功能，保持兼容
function greet(name, formal = false) {
  return formal ? 'Good day, ' + name : 'Hello, ' + name;
}

修订号（PATCH）：

当进行向后兼容的 Bug 修复时递增：

javascript

// v1.0.0
function divide(a, b) {
  return a / b;  // Bug: b 为 0 时出错
}

// v1.0.1 - Bug 修复
function divide(a, b) {
  if (b === 0) return 0;
  return a / b;
}

版本号优先级

比较版本号时，从左到右依次比较：

1.0.0 < 2.0.0 < 2.1.0 < 2.1.1

版本号规则

初始开发阶段

版本号以 0 开头表示初始开发阶段：

0.1.0
0.2.0
0.2.1

此时 API 可能随时变更，不建议用于生产环境。

正式版本

版本号以 1 开始表示正式版本：

1.0.0

此时 API 应该稳定，遵循语义化版本规范。

版本号示例

正常递增：

1.0.0 → 1.0.1  (Bug 修复)
1.0.1 → 1.1.0  (新功能)
1.1.0 → 2.0.0  (破坏性变更)

多级递增：

当次版本号递增时，修订号归零：

1.0.5 → 1.1.0

当主版本号递增时，次版本号和修订号归零：

1.9.9 → 2.0.0

预发布版本

预发布版本格式

主版本号.次版本号.修订号-预发布标识

示例：

1.0.0-alpha
1.0.0-alpha.1
1.0.0-beta
1.0.0-beta.2
1.0.0-rc.1

预发布版本类型

类型	说明	示例
alpha	内部测试版本	1.0.0-alpha
beta	公开测试版本	1.0.0-beta
rc	候选发布版本	1.0.0-rc.1

预发布版本优先级

预发布版本低于对应的正式版本：

1.0.0-alpha < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0

预发布版本之间的比较：

1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta

创建预发布版本

创建 alpha 版本：

bash

git tag -a v1.0.0-alpha -m "Alpha release"
git push origin v1.0.0-alpha

创建 beta 版本：

bash

git tag -a v1.0.0-beta -m "Beta release"
git push origin v1.0.0-beta

创建 RC 版本：

bash

git tag -a v1.0.0-rc.1 -m "Release candidate 1"
git push origin v1.0.0-rc.1

预发布工作流

开发 → alpha → 内部测试 → beta → 公开测试 → rc → 最终发布

示例流程：

bash

git checkout -b release/v1.1.0

git tag v1.1.0-alpha.1
git push origin v1.1.0-alpha.1

git tag v1.1.0-beta.1
git push origin v1.1.0-beta.1

git tag v1.1.0-rc.1
git push origin v1.1.0-rc.1

git tag v1.1.0
git push origin v1.1.0

版本标签策略

标签命名规范

标准版本：

v1.0.0
v1.1.0
v2.0.0

预发布版本：

v1.0.0-alpha.1
v1.0.0-beta.1
v1.0.0-rc.1

Git 标签管理

创建标签：

bash

git tag -a v1.1.0 -m "Release version 1.1.0"

查看标签：

bash

git tag -l "v1.*"

推送标签：

bash

git push origin v1.1.0

版本分支策略

Git Flow 版本分支：

main (生产)
  └── release/v1.1.0
        └── develop
              └── feature/*

GitHub Flow 版本标签：

main
  └── v1.0.0
  └── v1.1.0
  └── v1.2.0

约定式提交与版本

约定式提交格式

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

提交类型与版本关系

提交类型	版本变更	示例
feat	MINOR	feat: add user login
fix	PATCH	fix: resolve login error
BREAKING CHANGE	MAJOR	feat!: change API format
docs	无	docs: update README
style	无	style: format code
refactor	无/其他	refactor: restructure auth
test	无	test: add unit tests
chore	无	chore: update dependencies

自动版本管理

使用 standard-version：

bash

npm install -D standard-version

配置 package.json：

json

{
  "scripts": {
    "release": "standard-version"
  }
}

运行：

bash

npm run release

使用 semantic-release：

bash

npm install -D semantic-release

配置 .releaserc.json：

json

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

版本变更示例

PATCH 版本：

bash

git commit -m "fix: resolve timeout issue"
git push origin main

自动发布：1.0.0 → 1.0.1

MINOR 版本：

bash

git commit -m "feat: add export feature"
git push origin main

自动发布：1.0.1 → 1.1.0

MAJOR 版本：

bash

git commit -m "feat!: change API response format

BREAKING CHANGE: API response format changed from XML to JSON"
git push origin main

自动发布：1.1.0 → 2.0.0

版本范围语法

npm 版本范围

语法	含义	匹配版本
`1.2.3`	精确版本	1.2.3
`^1.2.3`	兼容版本	≥1.2.3 <2.0.0
`~1.2.3`	近似版本	≥1.2.3 <1.3.0
`>1.2.3`	大于	>1.2.3
`>=1.2.3`	大于等于	≥1.2.3
`<1.2.3`	小于	<1.2.3
`<=1.2.3`	小于等于	≤1.2.3
`1.2.x`	通配符	1.2.0, 1.2.1, ...
`*`	任意版本	所有版本

版本范围组合

区间范围：

json

{
  "dependencies": {
    "lodash": ">=1.0.0 <2.0.0"
  }
}

或运算：

json

{
  "dependencies": {
    "lodash": "1.2.3 || 1.3.0"
  }
}

最佳实践

生产依赖：

json

{
  "dependencies": {
    "express": "^4.18.0"
  }
}

开发依赖：

json

{
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

精确版本：

json

{
  "dependencies": {
    "critical-lib": "1.2.3"
  }
}

版本管理工具

npm version

更新版本号：

bash

npm version patch  # 1.0.0 → 1.0.1
npm version minor  # 1.0.1 → 1.1.0
npm version major  # 1.1.0 → 2.0.0

创建预发布版本：

bash

npm version prerelease --preid=beta  # 1.0.0 → 1.0.1-beta.0

自定义版本号：

bash

npm version 1.2.3

自动化版本管理

package.json 配置：

json

{
  "scripts": {
    "release": "npm version && git push --tags",
    "release:patch": "npm version patch && git push --tags",
    "release:minor": "npm version minor && git push --tags",
    "release:major": "npm version major && git push --tags"
  }
}

总结

语义化版本通过版本号传达变更含义
MAJOR.MINOR.PATCH 分别表示不同级别的变更
预发布版本用于测试，优先级低于正式版本
结合约定式提交实现自动化版本管理
使用版本范围管理依赖版本
选择合适的工具简化版本管理流程

语义化版本 ​

概述 ​