开源项目的版本标签如何规范命名

本文目录导读：

1. 核心标准：语义化版本控制（SemVer）
2. 扩展规范：预发布版本与构建元数据
3. 其他常见命名规范
4. 常见错误与最佳实践
5. 一个完整的版本标签生命周期示例

开源项目的版本标签规范命名通常遵循 语义化版本控制（Semantic Versioning，简称 SemVer），这是最广泛使用的标准，根据项目类型（如软件库、应用、前端模块等），还有一些补充规范。

核心标准：语义化版本控制（SemVer）

格式为：主版本号.次版本号.修订号（v1.2.3）。

• 主版本号（MAJOR）：当你做了不兼容的 API 修改。
  • 示例： 从 v1.x.x 升级到 v2.0.0 时，旧代码可能无法运行。
• 次版本号（MINOR）：当你做了向下兼容的功能性新增。
  • 示例： 从 v1.1.0 升级到 v1.2.0，旧功能不变，新增了一个特性。
• 修订号（PATCH）：当你做了向下兼容的问题修正。
  • 示例： 从 v1.2.0 升级到 v1.2.1，修复了一个 Bug，无新功能。

关键规范：

1. 版本号前通常加 v： 这是 Git 标签的惯例，v1.2.3，但有些项目（如 npm 包）内部可能省略 v，标签仍保留。
2. 版本号必须严格递增： v1.2.3 之后不能是 v1.2.2。
3. 一旦发布，就不能修改标签内容： 不能对已发布的 v1.2.3 重新打包，必须发布 v1.2.4。
4. y.z 是初始开发阶段： 主版本为 0 表示项目尚未稳定，任何更改都可能不兼容，通常用户在 x 版本时不会预期稳定 API。

扩展规范：预发布版本与构建元数据

用于标记正式版之前的测试版、候选版等。

格式：主版本号.次版本号.修订号-预发布标识符+构建元数据（v1.0.0-alpha.1、v2.0.0-rc.2）。

• 预发布标识符：
  • alpha：内部测试版，功能不完全，bug 很多。
  • beta：公测版，功能基本完成，用于收集用户反馈。
  • rc：候选发布版（Release Candidate），功能与正式版一致，用于最终测试，若无重大问题即转为正式版。
  • dev：每日构建或开发中版本。
  • snapshot（常用于 Java/Maven）：表示不稳定快照，可被覆盖。
• 命名规则： 预发布标识符后通常跟递增的数字，如 -alpha.1、-beta.2，数字用于区分同一阶段的多个版本。
• 优先级： 预发布版本的优先级低于对应的正式版。v1.0.0-alpha < v1.0.0-rc < v1.0.0。

示例：

v1.0.0-alpha.1
v1.0.0-alpha.2
v1.0.0-beta.1
v1.0.0-rc.1
v1.0.0       // 正式版
v1.0.1
v1.1.0
v2.0.0-alpha.1

其他常见命名规范

常见错误与最佳实践

1. 避免使用 latest 或 stable 作为唯一标签： 这些应该作为指向具体版本（如 v1.2.3）的别名，每次新版本发布时更新它，否则无法回溯过去版本。
2. 不要重复利用版本号： v1.2.3 发布了，就永远不要对 v1.2.3 重新打包推送，这是对使用者的基本尊重。
3. 对于私有库或企业级项目： 可以增加自定义后缀，但需内部约定，v1.0.0-hotfix.3。
4. 对于前端/JS 库： 严格遵循 SemVer，不要轻易在中版本号中引入破坏性变更，否则会导致生态灾难。
5. 对于 CLI 工具（如 git、kubectl）： 主版本号常因 CLI 参数的不兼容更改而增加。

一个完整的版本标签生命周期示例

v0.1.0               // 首次发布（不稳定）
v0.2.0-alpha.1       // 下一个大版本的新功能内测
v0.2.0-beta.1        // 公测
v0.2.0               // 稳定版发布
v1.0.0-alpha.1       // 准备第一个稳定主版本
v1.0.0-beta.1
v1.0.0-rc.1
v1.0.0               // 正式发布 v1.0.0
v1.0.1               // 修复一个漏洞
v1.1.0               // 新增一个功能
v2.0.0-alpha.1       // 不兼容的重构开始
...

最终建议： 对于绝大多数开源项目，严格遵循语义化版本控制 就是最好的规范，在发布前使用 alpha、beta、rc 等前缀来标记预发布版本，这样既能清晰地传达版本之间的兼容性，也能让使用者放心升级。