npm核心版本类型解释

6 阅读3分钟

语义化版本控制(Semantic Versioning,简称 SemVer) 的核心概念。理解它们对发布和管理 npm 包至关重要。

prereleasepatchminormajor 代表了不同类型的版本更新


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 开始)何时使用?对用户的影响
主版本major2.0.0做了不兼容的 API 更改,需要修改代码才能升级
次版本minor1.3.0新增向下兼容的功能,可安全升级,获得新功能
修订版本patch1.2.4修复了向下兼容的 bug非常小,应尽快升级以修复问题
预发布prerelease1.3.0-alpha.0 2.0.0-beta.1发布测试版供用户尝鲜和反馈不稳定,普通用户不应在生产环境使用

给你的建议

对于一个新包(比如你现在的 0.0.2):

  1. 如果你修复了一个bug -> 发布 patch 版本:0.0.3
  2. 如果你添加了一个新功能,但所有现有代码仍能工作 -> 发布 minor 版本:0.1.0
  3. 如果你想发布一个测试版让其他人试用新功能 -> 发布 prerelease 版本:0.1.0-beta.0
  4. 当你认为API已经非常稳定,可以用于生产了 -> 发布第一个 major 版本:1.0.0

记住一个原则:在 1.0.0 之前,你的所有API都被视为是不稳定的,任何次版本号(0.x.0)的更新都可以包含破坏性变更。 所以很多人会等到API稳定后直接发布 1.0.0