开源版本号该如何规范？

wen 开源项目 2026-06-11 264

本文目录导读：

开源版本号该如何规范？

为开源项目规范版本号，最推荐的做法是遵循语义化版本（Semantic Versioning，简称 SemVer，语义化版本规范），这是目前开源社区（如 npm、GitHub、PyPI、Rubygems 等）最广泛采用的规范。

核心：语义化版本（SemVer）

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

你需要根据代码变更的性质来决定递增哪个数字：

主版本号（Major）： 当你做了不兼容的 API 修改，这意味着用户从旧版本升级到新版本时，必须修改自己的代码才能正常工作。
- 例子： 删除了一个公共函数、修改了函数的参数类型、改变了返回值的格式。
次版本号（Minor）： 当你做了向下兼容的功能性新增，这意味着用户从旧版本升级到新版本时，无需修改自己的代码，就能获得新功能。
- 例子： 新增了一个公共函数、增加了一个可选参数、添加了一个新模块。
修订号（Patch）： 当你做了向下兼容的问题修正，这意味着用户升级后，不会有任何新功能，只会修复 bug 或进行性能优化。
- 例子： 修复了一个导致程序崩溃的 bug、优化了某个算法的效率、修复了文档拼写错误。

更多补充规则（格式：主.次.修-预发布标识+构建元数据）：

预发布版本（Pre-release）： 在修订号后加一个连字符和标识符（如 -alpha.1， -beta.2， -rc.1），它的优先级低于正式版本（0.0-alpha < 0.0）。
构建元数据（Build Metadata）： 在版本号后加一个加号和标识符（如 0.0+20231027），它仅用于标识构建信息,排序时会被忽略。

自动更新（依赖管理）： 包管理工具（如 npm, pip, cargo）可以根据版本号自动判断如何安全地更新依赖。
- 一般允许符号表示锁定主版本，接受次版本和修订版更新（如 ^1.2.3 允许 x.x 范围内的更新）。
- 波浪号表示只接受修订版更新（如 ~1.2.3 允许 2.x 范围内的更新）。
清晰的沟通： 看到版本号，开发者立刻知道升级的风险有多大（主版本=高危，次版本=低风险，修订版=无风险）。
行业共识： 你的用户和贡献者会立刻理解你的版本策略。

虽然 SemVer 是主流,但有些特定场景会采用其他风格：

CalVer（日历化版本）：
- 格式： YY.MM.MINOR 或 YYYY.MM.DD（10.1， 10.27）。
- 适用场景： 项目发布节奏很固定，与时间紧密相关，或者用户不关心 API 兼容性（如 Ubuntu 的版本号 04，Python 的 12）。
- 缺点： 无法直接体现 API 兼容性。
ZeroVer（零基础版本）：
- 格式： 永远停留在 x.y。
- 适用场景： 项目处于非常早期的快速迭代阶段，开发者不想承诺任何 API 稳定性。
- 注意： 这实际上是 SemVer 的一部分（y.z 阶段被视为开发阶段）,但有些项目会长期停留在此阶段。
不带三位数的版本（如 0 或 11）：
- 适用场景： 大型商业软件或游戏（如 Windows 10、Chrome 100、macOS 14）。
- 缺点： 这种版本号暗示了“大功能发布”，但无法体现补丁或微调,不适合依赖管理的自动化。

从 1.0 开始，而不是 0.1： 0.1 通常表示“第一次提交”，而 1.0 意味着项目已经有一些可用的功能了。
在文档或 README 中明确声明你的版本策略。 该项目遵循语义化版本 2.0.0。
使用 Git Tag 标记版本。 每次发布正式版本时，在 Git 上打一个对应版本号的 tag（如 v1.2.0）。
自动化发布流程（推荐）： 使用工具（如 standard-version， changesets，或 semantic-release）根据 Git 提交信息自动生成版本号和 changelog,这能有效避免人为错误。
在主版本号.0.0 的版本发布前，可以频繁发布 x.y 版本。 这表示你的 API 还不稳定。
第一个稳定版本通常是 0.0。 当你的 API 稳定下来，并且你觉得“这个项目已经可以投入生产使用了”时，就发布 0.0。