发布 NPM 包前需要知道的一些 NPM 包版本知识🌟

1,275 阅读2分钟

当需要发布一个 NPM 包时,我们要关注 package.json 中的 nameversion 字段,name 即包名称,version 即包版本,这两者可以唯一标识一个 npm 包。

包版本

包版本规范可以参考 Semantic Versioning。一个正式的版本分为三个部分,MAJOR.MINOR.PATCH,如 11.0.1。其中:

  • MAJOR 是不兼容的修改
  • MINOR 是向后兼容的功能添加
  • PATCH 是向后兼容的 bug 修复

一些最佳实践 🌟

  1. 使用版本的同时我们需要声明库的公共 API,以帮助开发者使用我们的库。API 需要是正确和可理解的,我们可以将它维护在文档里,并在需要修改时更新。

  2. 一次版本发布只能修改 X.Y.Z 里 X,Y,Z 中的一个,且只能递增 1,如 1.9.0 -> 1.10.0 -> 1.11.0。

  3. 一个版本的包发布后,这个版本的内容就不能再修改了!任何修改只能在新的版本中发布。

  4. PATCH 版本(即 X.Y.Z 中的 Z):只有在进行向后兼容的 bug 修复(修改一个版本中的错误内容)时递增。

  5. MINOR 版本(即 X.Y.Z 中的 Y):当新的向后兼容的功能被引入公共 API 或任何公共 API 功能被标记为弃用时必须递增。当 MINOR 版本递增时 PATCH 版本必须重置为0

  6. MAJOR 版本:当任何不向后兼容的功能被引入公共 API 时必须递增。当 MAJOR 版本递增时 MINOR 和 PATCH 版本必须重置为0。

  7. 预发布版本:预发布版本指示某个版本不稳定,可能无法满足其关联的正常版本所示的预期兼容性要求。预发布版本会在 X.Y.Z 之后添加一些字符,示例:1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.–。

版本优先级

当命令中的包不带版本时,如 npm install react,会默认安装优先级最高的包版本。

版本优先级顺序依次由 MAJOR,MINOR,PATCH 的字母大小来判定,如 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1。预发布版本的优先级比其关联的正常版本的优先级低,如 1.0.0-alpha < 1.0.0。

~^ 符号

有时候我们会在版本中看到~^ 这两个符号,它们是什么意思呢?

~version 为当前版本的最新修复版

~ 将会把 PATCH 版本更到最新,但不会更改 MINOR 版本。如 ~1.2.3 ,如果存在 1.2.41.2.51.3.0,则将会自动安装 1.2.5。如这里安装 "lodash": "~4.16.0",最后安装的版本为 4.16.6

截屏2021-11-17 下午3.24.20

^version 为当前版本的最新兼容版

^ 将会把 MINOR 和 PATCH 版本更到最新,但不会更改 MAJOR 版本。如 ^1.2.3 ,如果存在 1.2.4,...,1.4.52.0.0,则将会自动安装 1.4.5。同样以 lodash 为例,安装 "lodash": "^4.0.0",最后安装的是最新版本 4.17.21

npm version

我们可以借助 npm version <major | minor | patch | prerelease> 命令来帮助我们修改版本号。如 npm version minor 将会修改 package.json 中 version 字段的 MINOR ,将其递增。

参考

  1. npm package-json

  2. Semantic Versioning

  3. whats-the-difference-between-tilde-and-caret-in-package-json