三个数字,一份承诺
语义化版本为每个位置赋予含义:公共 API 不兼容时递增 MAJOR,向后兼容地新增功能时递增 MINOR,向后兼容地修复缺陷时递增 PATCH。2.0.0-rc.1 这样的预发布标识排在正式版之前,加号之后的构建元数据不参与优先级比较。版本号是维护者与使用者之间的沟通契约。
1.4.2 -> 1.4.3 patch:缺陷修复,可安全采用
1.4.2 -> 1.5.0 minor:新增功能,向后兼容
1.4.2 -> 2.0.0 major:破坏性变更,先读迁移指南
何时使用
任何被他人依赖的包都应使用语义化版本,包括内部共享库。要配合变更日志与弃用策略,因为数字本身并不说明改了什么。从不作为依赖被消费的应用收益较小,但发布说明仍可采用同样的纪律。
权衡
语义化版本只有在维护者诚实、使用者理解的前提下才有效。^1.2.0 这样的范围假设维护者从不在 minor 版本中破坏兼容性,而这一假设经常失效,所以锁文件仍不可少。严格实践也增加发布开销;界定什么是公共 API 是设计决策,而不是格式问题。
示例与常见误解
某 UI 库新增一个可选属性:递增 minor,使用 ^3.4.0 的应用自动获得。后来它重命名某个属性:递增 major,变更日志提供 codemod。认为语义化版本能防止破坏的误解很危险,它只是标注风险。相关概念包括依赖固定、向后兼容与 CI/CD。