npm version: 轻松管理你的 npm 包版本

npm version 是管理 Node.js 项目版本号的一个命令行工具，依据语义化版本（Semantic Versioning）进行版本管理。

语义化版本是以 major.minor.patch 3 个数字的形式进行版本定义的。

1. 第一个数字表示主版本号（major），一般是在项目代码发生大的变动，或者引入了一个破坏性/不兼容变更时更新
2. 第二个数字表示次版本号（minor），一般是在项目引入新功能时更新
3. 第二个数字表示修订号（patch），一般是项目 BUG 修复，局部代码优化等涉及非功能性修改时更新

版本管理是项目发布流程里必不可少的一环，今天就来学习。

认识 npm

npm 全称 NPM Package Manager，是管理 Node.js 三方包的官方工具。在安装 Node.js 时，npm 会一起安装。

我们可以通过以下命令，检查 npm 版本。

# 查看当前 npm 版本
$ npm -v
8.19.2

必要时，可以依据下面的方式进行版本升级。

# 查看已发行的所有 npm 版本
$ npm view npm versions
# 升级 npm 到指定版本
$ npm install -g npm@10
# 升级 npm 到最新

帮助手册

我们还可以通过 npm help 指令获取帮助支持。

$ npm help version

通过 npm 管理版本

接下来，我们将通过语法以及具体参数使用来介绍 npm version。

语法

$ npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]

npm version 支持以直接输入版本号（比如：1.2.3）的方式升级版本；也支持以预定义关键字（patch、prepatch 等）的形式升级版本。

npm version <newversion>

先以 npm version <newversion> 为例，看看会发生什么（目前项目中 package.json 中的版本号是 1.0.0）。

# 获取 package.json 中的 version
$ npm pkg get version
"1.0.0"
# 指定版本进行升级
$ npm version 2.3.4
v2.3.4

# 查看结果

# 1) package.json 中的 version 顺利修改
$ npm pkg get version
"2.3.4"
# 2) 同时会在 git repo 上打一个 tag（包含前缀 `v`）
$ git tag -l
v2.3.4
# 3) 最后生成一个 git commit
# commit message 就是版本号
$ git log --oneline
f54a78d (HEAD -> main, tag: v2.3.4) 2.3.4

npm version 2.3.4 指令执行后，会做 3 处修改：

1. 将 package.json 中的 version 字段更新成 "2.3.4"
2. 生成一个 git commit，使用2.3.4作为commit message
3. 使用 v2.3.4（注：有一个 v 前缀） 打一个 tag

当然，git commit message 是可以通过-m（或 --message）参数自定义的。

$ npm version 3.4.5 -m "release: v%s"

$ git tag -l
v2.3.4
v3.4.5
$ git log --oneline   
dcde493 (HEAD -> main, tag: v3.4.5) release: v3.4.5
f54a78d (tag: v2.3.4) 2.3.4

通过 -m指定自定义commit message 信息，%s 是表示新版本号的占位符。

npm version major|minor|patch

目前版本号 v3.4.5。

$ npm version major
v4.0.0
$ npm version minor
v4.1.0
$ npm version patch
v4.1.1
$ npm tag -l
v2.3.4
v3.4.5
v4.0.0
v4.1.0
v4.1.1

• npm version major后，将 major 版本加 1，minor、patch版本都置为 0。即 v3.4.5 -> v(3+1).0.0，也就是 v4.0.0
• npm version minor后，major 不变，将 minor 版本加 1，patch 版本置为 0。即 v4.0.1 -> v4.(0+1).0，也就是 v4.1.0
• npm version patch后，major、minor 不变，将 patch(版本加 1。即 v4.1.0 -> v4.1.(0+1)，也就是 v4.1.1

npm version premajor|preminor|prepatch

目前版本号 v4.1.1。

$ npm version prepatch
v4.1.2-0
$ npm version preminor 
v4.2.0-0
$ npm version premajor
v5.0.0-0

观察发现，npm version prexxx 指令其就是在对应 npm version xxx 之上，增加 -0 的后缀。

不过，prexxx 通常都是配合 --preid=alpha|beta|rc 一起使用，指定创建某些阶段的测试版本。

npm version prepatch

目前版本号 v5.0.0-0。

$ npm version prepatch --preid=rc  
v5.0.1-rc.0
$ npm version prepatch --preid=rc
v5.0.2-rc.0
# 升级后缀版本
$ npm version prerelease
v5.0.2-rc.1

可以看到，在指定 --preid=rc 后，后缀由 -0 变为 -rc.0。

还需要注意的是，「在执行完 1 次 「**npm version prexxx**」 命令后，后续直接使用 「**npm version prerelease**」 就能自动升级后缀版本了」！

npm version preminor|premajor

目前版本号 v5.0.2-rc.1。

$ npm version preminor --preid=rc
v5.1.0-rc.0
$ npm version premajor --preid=rc
v6.0.0-rc.0

preminor、premajor 的使用与 prepatch 类似。

从 pre 版本升级到正式版本

目前版本号 v6.0.0-rc.0。

# 从 v6.0.0-rc.0 升级到 v6.0.0
$ npm version major
v6.0.0

$ npm version preminor --preid=rc
v6.1.0-rc.0
$ npm version prerelease
v6.1.0-rc.1
# 从 v6.1.0-rc.1 升级到 v6.1.0
$ npm version minor
v6.1.0

$ npm version prepatch --preid=rc
v6.1.1-rc.0
$ npm version prerelease
v6.1.1-rc.1
# 从 v6.1.1-rc.1 升级到 v6.1.1
$ npm version patch
v6.1.1

当我们想从测试版本（比如：本例中的 RC 版本）升级到正式版本的时候，只要执行相应的 npm run patch|minor|major 指令即可。

如果不清楚测试版本是以哪个为基准的，可以查看 tag 提交历史：

$ git tag --sort=-v:refname
v6.1.1-rc.1
v6.1.1-rc.0
v6.1.1
v6.1.0-rc.1
v6.1.0-rc.0
v6.1.0
v6.0.0-rc.0
v6.0.0
v5.1.0-rc.0
v5.0.2-rc.1
v5.0.2-rc.0
v5.0.1-rc.0
v5.0.0-0
v4.2.0-0
v4.1.2-0
v4.1.1
v4.1.0
v4.0.0
v3.4.5
v2.3.4

好了，现在我们查看下到目前为止的提交历史。

$ git log --oneline
a6f3a0c (HEAD -> main, tag: v6.1.1) 6.1.1
575da4c (tag: v6.1.1-rc.1) 6.1.1-rc.1
17707a3 (tag: v6.1.1-rc.0) 6.1.1-rc.0
308b02e (tag: v6.1.0) 6.1.0
478e885 (tag: v6.1.0-rc.1) 6.1.0-rc.1
708215c (tag: v6.1.0-rc.0) 6.1.0-rc.0
47ed235 (tag: v6.0.0) 6.0.0
a1cfc10 (tag: v6.0.0-rc.0) 6.0.0-rc.0
cd54e40 (tag: v5.1.0-rc.0) 5.1.0-rc.0
1f1003e (tag: v5.0.2-rc.1) 5.0.2-rc.1
d89c463 (tag: v5.0.2-rc.0) 5.0.2-rc.0
ae8457d (tag: v5.0.1-rc.0) 5.0.1-rc.0
a84fb76 (tag: v5.0.0-0) 5.0.0-0
0e771e6 (tag: v4.2.0-0) 4.2.0-0
e659fb5 (tag: v4.1.2-0) 4.1.2-0
393fe7d (tag: v4.1.1) 4.1.1
d09b17c (tag: v4.1.0) 4.1.0
fc76e93 (tag: v4.0.0) 4.0.0
dcde493 (tag: v3.4.5) release: v3.4.5
f54a78d (tag: v2.3.4) 2.3.4

可以看到，每次提交都对应一个 tag。

生命周期脚本

npm version 指令在执行过程中，会运行 package.json 中的一些脚本。

具体执行顺序如下：

1. 首先确保 git 工作目录（workingdirectory）是干净的，否则会报错。当然，可以通过指定 –force 参数，就不会报错了
2. 「执行 preversion 脚本」。这个阶段的典型应用是在提交之前「运行完整的测试套件」
3. 升级 package.json 中的 version 字段
4. 「执行 version 脚本」。这个阶段的典型应用是「通过 git add 显式地将生成的文件添加到提交中」
5. 生成 gitcommit(犯)记录，同时打 tag
6. 「执行 postversion 脚本」。这个阶段的典型应用是「清理文件系统」或「推送提交记录或 tag」

下面是一个例子：

{
  "scripts": {
    "preversion": "npm test",
    "version": "npm run build && git add -A dist",
    "postversion": "git push && git push --tags && rm -rf build/temp"
  }
}

–no-git-tag-version flag

执行 npm verison 时指定 --no-git-tag-version flag，就不会创建版本提交和打 tag 了——只更新 package.json 中的 version 版本。很少用。

$ npm --no-git-tag-version version 7.8.9
v7.8.9

总结

本文介绍如何使用 npm version 命令管理项目版本。先后讲解了如何指定版本升级，如何基于现有版本做正式版本和 pre 版本的升级，以及如何从 pre 版本升级到正式版本。

另外，npm version 执行期间也会触发 package.json 中的一些生命周期脚本，我们可以基于这些钩子脚本做项目资源的管理。