语义化版本 2.0.0

《语义化版本 2.0.0》，三段版本号语义：

版本格式：主版本号.次版本号.修订号（MAJOR.MINOR.PATCH），版本号递增规则如下：

  1. 主版本号（MAJOR）：当你做了不兼容的 API 修改，
  2. 次版本号（MINOR）：当你做了向下兼容的功能性新增，
  3. 修订号（PATCH）：当你做了向下兼容的问题修正。

先行版本号及版本编译信息可以加到"主版本号.次版本号.修订号"的后面，作为延伸。例如 1.0.0-alpha、1.0.0-beta.1、1.0.0-0.3.7。

版本号的初始阶段

在主版本号为 0.x.y 的阶段，API 被认为是不稳定的，任何变更都可能发生。这个阶段的软件不应该被用于生产环境。1.0.0 的发布意味着公共 API 的正式定义，后续的版本号变更都基于这个公共 API 的变化来递增。

先行版本号（Pre-release）

先行版本号通过在修订号后面加上连字符和一系列以点分隔的标识符来表示。例如：

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

常见的先行版本标识符包括：

  • alpha：内部测试版，可能存在较多缺陷
  • beta：公开测试版，功能基本完整但可能有缺陷
  • rc（Release Candidate）：发布候选版，如果没有发现重大问题就会成为正式版

版本编译信息（Build Metadata）

版本编译信息通过在修订号或先行版本号后面加上 + 号和一系列以点分隔的标识符来表示。例如 1.0.0+20130313144700、1.0.0-beta+exp.sha.5114f85。编译信息在判断版本优先级时应该被忽略。

语义版本化在实践中的常见问题

依赖地狱（Dependency Hell）

语义版本化试图解决的核心问题就是依赖地狱。在大型系统中，依赖关系越来越多、越来越复杂，如果没有统一的版本管理规范：

  • 版本锁死（Version Lock）：为了避免不兼容，所有依赖都锁定在特定版本，导致无法升级任何一个包
  • 版本混乱（Version Promiscuity）：对版本兼容性过于乐观，假设所有新版本都兼容，最终导致运行时错误

版本范围表达式

不同的包管理器使用不同的语法来表达版本范围：

  • npm/yarn：^1.2.3（兼容 1.x.x）、~1.2.3（兼容 1.2.x）、>=1.0.0 <2.0.0
  • Maven：[1.0,2.0)（大于等于 1.0 且小于 2.0）
  • Bundler (Ruby)：~> 1.2（大于等于 1.2 且小于 2.0）

其中 npm 的 ^（caret）和 ~（tilde）是最容易混淆的：

  • ^1.2.3 表示 >=1.2.3 <2.0.0，允许 MINOR 和 PATCH 级别的变更
  • ~1.2.3 表示 >=1.2.3 <1.3.0，只允许 PATCH 级别的变更

语义版本化的局限性

  1. 语义是主观的：什么算"不兼容的变更"往往取决于使用者的视角。一个被标记为 PATCH 的修复可能改变了某些用户依赖的行为（即使那个行为本身是 bug）。
  2. 不能覆盖所有变更类型：性能退化、内存占用增加、行为的微妙变化等，都不容易用三段版本号来表达。
  3. 人为错误：版本号的递增依赖于开发者的判断和自律，实践中经常出现 MINOR 版本引入破坏性变更的情况。

相关的版本化策略

CalVer（日历版本化）

CalVer 使用日期作为版本号的基础，例如 Ubuntu 的 22.04（2022年4月发布）。适用于发布周期固定、不强调 API 兼容性的项目。

零版本化（ZeroVer / 0ver）

一些项目长期停留在 0.x.y，永远不发布 1.0.0，以此规避语义版本化对稳定性的承诺。这种做法虽然"合规"，但违背了语义版本化的精神。

内部版本号 vs 市场版本号

很多商业软件同时维护两套版本号：内部使用语义版本号进行依赖管理，对外使用市场版本号（如 Windows 11、macOS Ventura）进行品牌传播。两者的递增逻辑完全不同。

各语言生态的版本化实践

生态 包管理器 版本规范 特点
Node.js npm/yarn SemVer 严格遵循，package-lock.json 锁定精确版本
Java Maven/Gradle SemVer（非强制） SNAPSHOT 机制用于开发版本
Python pip PEP 440 支持 epoch、dev/post release 等扩展
Ruby Bundler SemVer Gemfile.lock 锁定版本
Go go modules SemVer v2+ 需要改变 import path
Rust Cargo SemVer 编译器级别的版本兼容性检查

Go 语言的做法尤其值得一提：当主版本号升级到 v2 及以上时，import path 必须包含版本后缀（如 github.com/user/repo/v2），这从语言层面强制了不兼容版本的隔离。