语义化版本（SemVer）

2025年07月29日 Tags: Js

版本格式：

Major.Minor.Patch（主版本号.次版本号.修订号）

版本号递增规则：

主版本号：当做了不兼容的 API 修改时递增。
次版本号：当做了向下兼容的功能性新增时递增。
修订号：当做了向下兼容的问题修正时递增。

1.主版本号递增时，次版本号和修订号必须归零。次版本号递增时，修订号必须归零。

2.次版本号在任何公共 API 的功能被标记为弃用时也须递增。也可以在内部程序有大量新功能或改进被加入时递增，其中可以包括修订级别的改变。

❓“向下兼容”和“不向下兼容”指的是什么？

向下兼容（Backward Compatible）

新版本的 API 在功能上不会破坏旧版本的行为，旧代码在新版本中仍然可以正常运行。

例如：

新增 API
新增可选参数
添加新事件、新字段、新返回值
修复 Bug

不向下兼容（Breaking Change/Not Backward Compatible）

新版本的 API 会破坏旧版本的行文，可能导致旧代码无法正常运行。

例如：

删除 API
修改 API 名称或签名
修改参数类型或含义
修改返回值结构
修改默认行为
限制功能或移除功能

先行版本号（Pre-release Version）

表示某个版本时尚未正式发布的预发布版本。通常用于测试、内部使用或早期体验。

格式：Major.Minor.Patch-Pre.Release

先行版本号可以被标注在修订号之后，格式为先加上一个连接号- 再加上一连串以句点 . 分隔的标识符来修饰。标识符必须由 ASCII 字母数字和连接号 [0-9A-Za-z-] 组成，且禁止留白。

示例：

1.0.0-alpha 表示主版本的第一个测试版本，处于 alpha 阶段。
1.0.0-rc.1 表示第一个发布的候选版本。
1.0.0-nightly.20240120 表示夜间构建版本，时间为2024年1月20日。

先行版本标识符：

标识符	说明
`alpha`	早期测试版本，功能尚未完整
`beta`	功能基本完成，仍在测试阶段
`rc`	候选发布版本
`dev`	开发版本（仅供开发测试）
`nightly`	夜间构建版本
`preview`	预览版本
`experimental`	实验性版本

版本编译信息（Build Info/Build Metadata）

附加在版本号之后，用于描述构建过程相关信息的元数据。

格式：Major.Minor.Patch[-Pre.Release]+Build.Info

先加上一个加号 + 再加上一连串以句点 . 分隔的标识符来修饰。标识符必须由 ASCII 字母数字和连接号 [0-9A-Za-z-] 组成，且禁止留白。

示例：

1.0.0+20240120 表示版本构建时间为2024-01-20
1.0.0-beta+git.abc123 表示来自 Git 的提交，hash前几位为abc123
1.0.0+linux-x64 表示构建平台为 Linux x64
1.0.0-alpha+docker.build-123 表示来自 Docker 的构建任务 123
2.1.0+ci.build-456.git.def567 表示来自 CI 构建任务 456，Git 提交为 def567

常见的版本编译信息内容：

Git 提交哈希
构建时间
CI/CD 流水线时间
构建平台（操作系统）例如：linux-x64、win32、darwin
Docker 构建标签
用户名或构建者例如：build-by.john

⚠️注意事项

禁止在数字前方补零，每个元素必须以数值来递增。
带有先行版本号的版本低于没有先行版本号的版本。
判断版本的优先级时，编译信息可被忽略。

版本范围指示符

指示符	说明	用途
`^`	允许次版本号和修订号升级，但不改变主版本号	建议开发环境使用
`~`	允许修订号升级，但不改变次版本号和主版本号	建议生产环境使用
`>`	大于指定版本
`<`	小于指定版本
`=`	精确匹配，可省略，锁版本号	建议生产环境使用
`*`	接受任何版本
`x`	通配符	示例：`1.x` `1.2.x` `x.x.x` (同 `*`)

参考链接

语义化版本 2.0.0

语义化版本 （SemVer）