语义化版本控制(Semantic Versioning,简称 SemVer) 的核心概念。理解它们对发布和管理 npm 包至关重要。
prerelease、patch、minor、major 代表了不同类型的版本更新。
1. major (主版本号,例如:1.0.0 -> 2.0.0)
- 含义:不兼容的 API 修改。当你做了无法向下兼容的改动时,需要升级主版本号。
- 何时使用:
- 移除或更改了公共 API(函数、组件、配置项的名称或行为发生了破坏性变更)。
- 大范围的重构,导致用户升级后他们的代码很可能需要修改。
- 提示:升级主版本号意味着你向用户传达一个明确信息:“这次更新需要你仔细检查代码,可能会有东西不 work 了。”
2. minor (次版本号,例如:1.0.0 -> 1.1.0)
- 含义:向下兼容的功能性新增。当你新增了功能,但所有现有功能都保持兼容。
- 何时使用:
- 添加了一个新的函数、组件或特性。
- 在现有功能上添加了可选的新参数。
- 任何不会破坏现有代码的新增内容。
- 提示:这是最常见的更新类型。它告诉用户:“可以安全升级,有新东西可以用了,但不会搞砸你现在的代码。”
3. patch (修订号,例如:1.0.0 -> 1.0.1)
- 含义:向下兼容的问题修正。用于修复 bug,没有新增任何功能。
- 何时使用:
- 修复了某个功能的错误逻辑。
- 改进了性能(但行为不变)。
- 修正了文档或注释。
- 提示:它告诉用户:“这是一个重要的bug修复,你应该尽快升级以确保稳定。”
预发布版本解释
4. prerelease (预发布版本,例如:0.0.2-rc.1, 1.0.0-beta, 2.1.0-alpha.3)
- 含义:不稳定版本,用于在正式版发布之前进行测试。它附在基本版本号之后,用连字符
-连接标识符。 - 常见标识符(按稳定性排序):
alpha: 内测版,最初期的版本,功能不稳定,仅供内部测试。beta: 公测版,功能相对稳定,开放给外部用户测试,但可能仍有bug。rc(Release Candidate): 发布候选版,非常接近正式版,如果没有发现重大bug,就会成为正式版。
- 何时使用:
- 你想让一部分用户(测试人员)提前体验新功能并反馈问题。
- 你想在发布一个重大更新(如
major版本)前进行大规模测试。
- 重要特性:
- 用户使用
npm install your-package默认不会安装预发布版本。 - 必须明确指定版本号才能安装,例如
npm install your-package@0.0.2-rc.1。 - 预发布版本的号可以重复更新(例如可以从
rc.1发布到rc.2,只修改后缀)。
- 用户使用
如何区分和选择?一张表搞定
| 更新类型 | 英文名 | 版本示例 (从 1.2.3 开始) | 何时使用? | 对用户的影响 |
|---|---|---|---|---|
| 主版本 | major | 2.0.0 | 做了不兼容的 API 更改 | 大,需要修改代码才能升级 |
| 次版本 | minor | 1.3.0 | 新增向下兼容的功能 | 小,可安全升级,获得新功能 |
| 修订版本 | patch | 1.2.4 | 修复了向下兼容的 bug | 非常小,应尽快升级以修复问题 |
| 预发布 | prerelease | 1.3.0-alpha.0 2.0.0-beta.1 | 发布测试版供用户尝鲜和反馈 | 不稳定,普通用户不应在生产环境使用 |
给你的建议
对于一个新包(比如你现在的 0.0.2):
- 如果你修复了一个bug -> 发布 patch 版本:
0.0.3 - 如果你添加了一个新功能,但所有现有代码仍能工作 -> 发布 minor 版本:
0.1.0 - 如果你想发布一个测试版让其他人试用新功能 -> 发布 prerelease 版本:
0.1.0-beta.0 - 当你认为API已经非常稳定,可以用于生产了 -> 发布第一个 major 版本:
1.0.0
记住一个原则:在 1.0.0 之前,你的所有API都被视为是不稳定的,任何次版本号(0.x.0)的更新都可以包含破坏性变更。 所以很多人会等到API稳定后直接发布 1.0.0。