package.json 文件是 Node.js 项目中的一个重要文件,它包含了项目的各种元信息,如项目名称、版本、描述、依赖关系等。其中,版本规则是 package.json 文件中的一部分,用于指定项目的版本号。

版本声明规则

package.json的版本号规则遵循 SemVer 规则,一般格式如下

{
  "name": "my-project",
  "version": "1.2.3"
}

可以看出,版本号通常以一个字符串的形式表示,格式为 MAJOR.MINOR.PATCH,其中 MAJORMINORPATCH 都是非负整数,分别代表主版本号、次版本号和补丁版本号。这三个字母的含义分别如下:

  • MAJOR:主版本号,通常在进行了不兼容的API变更时增加。
  • MINOR:次版本号,通常在添加了新的功能或者在原有功能上进行改进,但仍然保持向下兼容时增加。
  • PATCH:补丁版本号,通常在进行了向下兼容的错误修复时增加。

可以看出,平时我们安装的包都是遵循这个规则的版本号,我们在开发一些通用的npm包时,也要遵循这个规则。通常要发布的时候我们可以手动修改 package.json 文件的 version 字段来调整版本,或者通过命令行工具也可以,比如以下命令:

  • 发布新子版本:npm version minor(递增次版本号)或 npm version patch(递增修订号)。
  • 发布 rc 版本:npm version prerelease --preid=rc

这些命令将自动更新 package.json 文件中的版本号,并将新版本发布到包管理器的注册表中。

版本修饰符

除了数字组成的版本号,我们还可以额外添加一些修饰符,修饰符是版本号的补充说明,用来表示该版本并非稳定或可能无法满足预期的兼容性需求。修饰符必须由ASCII字母数字和连接号组成,且禁止留白。数字型的修饰符禁止在前方补零。常见的修饰符如下表:

修饰符含义
alpha内部版本
beta测试版本
demo演示版本
enhance增强版本
fullVersion完整版本
final最终版本
ga(General Availability):发行稳定版
rc(Release Candidate):候选版本,几乎就是正式版了

我们平时在声明包版本时,可以参考当前项目的进展来使用对应的修饰符。

版本使用规则

在通过 npm i xxx 命令安装包到项目后,会在 package.json 文件生成对应的包以及版本号,通常位于 dependencies 或者 devDependencies 下面。例如

"dependencies": {
  "execa": "^8.0.1"
}

细心的朋友可能已经发现,为什么版本号前面有个特殊的箭头符号 ^ ,这个 ^ ,表示当更新包时,锁定主版本,将次版本更到最新。

除了 ^ 符号之外,其他符号的含义如下:

符号含义例子
^仅接受次要版本和补丁版本的更新。^0.13.0: 0.13.1,0.14.0
~仅接受补丁版本的更新。~0.13.00.13.1(不是0.14.0
>接受任何高于指定版本的更新。>0.13.0: 0.13.1, 0.14.1,1.1.1
<接受低于指定版本的任何版本的更新。<3.0.0: 2.0.0,2.9.0
>=接受大于或等于指定版本的任何版本。>=3.0.0: 3.0.0,4.1.0
<=接受小于或等于指定版本的任何版本。<=3.0.0: 3.0.0,4.1.0
=仅接受确切指定的版本。=3.0.03.0.0, (不是3.0.1
-接受一系列版本。1.0.0 - 1.10.101.5.0(不是1.11.0
||接受版本的组合。<2.1.0 || >2.6.0: 2.0.1,3.1.0
x.x.x仅接受指定版本(无符号)。=3.0.03.0.0, (不是3.0.1
latest始终获得可用的最新版本。-

我们可以按需使用对应的符号,通常如果项目比较旧,不适合更新包版本,可以通过锁定版本来解决,即不加符号,然后重新执行安装命令即可。

"dependencies": {
  "execa": "8.0.1"
}