首页/开发/Git 与协作速查/Semantic Versioning 语义化版本

Semantic Versioning 语义化版本

版本号含义约定:MAJOR.MINOR.PATCH;不兼容改动升主版本、兼容新增升次版本、兼容修复升修订号。

Git 与协作速查开发更新于 2026-10-13

语义化版本是什么

语义化版本约定版本号写成主版本、次版本、修订号三段,并给每段的递增赋予明确含义:不兼容的改动升主版本,兼容地新增功能升次版本,兼容地修复缺陷升修订号。它的价值在于让「看版本号就能判断升级风险」成为可能。

落地时的常见做法

版本号通常以标签形式打在发布提交上,附注标签还能带上说明与签名。与提交规范配合时,工具会根据提交里的类型自动推导该升哪一段,发布说明也一并生成。真正需要写清楚的是升级注意事项:哪些接口变了、使用方需要改什么配置。

基本信息

适用规范Semantic Versioning 2.0.0
格式主版本.次版本.修订号,可选预发布标识
递增规则不兼容升主版本;兼容新增升次版本;兼容修复升修订号
载体发布提交上的标签
标签形式正式发布建议使用附注标签,便于附带说明
配套内容变更说明与升级注意事项

典型使用场景

  • 发布管理:给每次对外版本一个可比较的编号
  • 依赖声明:用版本范围表达兼容区间
  • 自动定版:结合提交规范自动推导应升的段位
  • 沟通风险:用主版本变化提示下游需要适配
  • 回溯问题:按版本号找到对应发布提交与变更清单

编号含义示例

编号含义示例
1.4.2  修复版本,兼容
1.5.0  新增功能,兼容
2.0.0  不兼容变更
git tag -a v1.4.2 -m '修复分页越界'

三段含义

位置何时递增对使用方的影响
主版本出现不兼容改动需要适配后才能升级
次版本兼容地新增功能可直接升级,旧用法仍有效
修订号兼容地修复问题建议尽快升级
预发布标识正式发布前的测试版不承诺兼容,需谨慎引入
SemVer 2.0.0 是公开发布的规范文档,可以作为团队版本号规则的引用基线,减少口头约定带来的分歧。
0.y.z 阶段规则较宽松,任何版本都可能不兼容;1.0.0 起才按正式约定执行,依赖管理时要区别对待。

易错点

  • 0.y.z 阶段规则从宽,1.0.0 起才按正式约定执行,依赖管理要区别对待
  • 内部依赖与外部契约混用同一套版本号时,升级策略要写清楚
  • 只升版本号却不写变更说明,使用方无法判断升级需要做哪些改动
  • 用轻量标签随手标记正式发布,缺少说明信息,回溯时不易确认内容

数据来源与参考

  • Semantic Versioning 2.0.0(semver.org)
  • Conventional Commits 1.0.0(版本提升关联说明)
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌