流浪小猫的博客

npm 语义化版本号

· xcatliu

本文开始介绍了 npm 中语义化版本号的格式,然后对如何升级版本号进行了归纳,最后总结了如何正确的定义依赖的版本号。

认识 npm 版本号§

每一个 node package 都有自己的版本号,一般定义在项目的 package.json 中,如:

{
  "name": "express",
  "description": "Fast, unopinionated, minimalist web framework",
  "version": "4.12.3",
  "author": "TJ Holowaychuk <-media.ca>",
  "...": "..."
}

版本号的格式§

npm 基本遵守 semver 语义化版本号的规则,使用 node-semver 来解析版本号。

一般来说,一个版本号包含三个部分:

MAJOR.MINOR.PATCH

MAJOR 表示主版本号,MINOR 表示次版本号,PATCH 表示修订号。

它们的取值为非负整数,若大于零,不能在前方补零。

另外版本号中任何位置都不能有空格。

先行版本号(Pre-release Version)§

作为额外规则,先行版本号可以作为发布正式版之前的版本,格式是在修订版本号后面加上一个连接号(-),再加上一连串以点(.)分割的标识符,标识符可以由英文、数字和连接号([0-9A-Za-z-])组成。

同样若数字大于零,不能在前方补零,版本号中任何位置都不能有空格。

举例如下:

1.0​​.0-alpha
1.0.0-alpha.1
1.0.0-0.3.7
1.0.0-x.7.z.92

另外,以下列出了一些常见的先行版本号名称:

版本编译信息(Build Metadata)§

版本编译信息是另一个额外规则,格式是在修订版本号或先行版本号后面加上一个加号(+),再加上一连串以点(.)分割的标识符,标识符可以由英文、数字和连接号([0-9A-Za-z-])组成。

版本号中任何位置都不能有空格(数字表示编译信息,是可以在开头存在多个零的)。

举例如下:

1.0.0-alpha+001
1.0.0+20130313144700
1.0.0-beta+exp.sha.5114f85

一些拓展的版本号规则§

以上为标准的 semver 规则。阅读 node-semver 源码后,发现它对 semver 有了一些拓展:

  1. 允许版本号中大于零的数字以零开头
  2. 允许以 v 开头
  3. 允许以 = 开头
  4. 允许 v= 与版本号之间有空字符串
  5. 允许在开头包含空字符串
  6. 上面四个规则中,v= 和空字符串都允许出现多次

更深入的讲,node-semver 提供了两种模式,普通模式和宽松模式,普通模式包含了上面 2 的拓展,宽松模式包含了以上所有拓展。

npm 使用的是 semver 的宽松模式。

具体内容可以阅读源码了解。

如何升级版本号§

升级版本号的规则主要有三个:

  1. 主版本号:当你做了不兼容的 API 修改
  2. 次版本号:当你做了向下兼容的功能性新增
  3. 修订号:当你做了向下兼容的问题修正

开发阶段的版本号§

主版本号为零的时候,属于开发阶段,一切都可能随时改变,故以上三个规则也不一定适用。

一般来说,修订号的修改仍然保持向下兼容,但是次版本号就不一定向下兼容了。

先行版本号§

先行版本号一般用于发布一个新的主版本号(比如 1.0.02.0.03.0.0)之前,同样是不一定兼容的。

另一些的规则§

  1. 任何时候都禁止修改已发布的版本的内容,任何修改都必须以新版本发布
  2. 次版本号的升级,必须把修订号归零
  3. 主版本号的升级,必须把次版本号和修订号归零

如何正确的定义依赖的版本号§

在 node package 中,经常需要依赖一些 npmjs.com 上的资源,使用 npm install express --savenpm install express --save-dev 即可在安装的同时,把依赖关系写入 package.jsondependenciesdevDependencies 中。

  "dependencies": {
    "express": "^4.12.3"
  },

默认会在版本号前面加上一个 ^,在 npm 的依赖的规则中,还有 ~><=>=<=-||xX* 等符号,下面会一一解释。

^§

表示同一主版本号中,不小于指定版本号的版本号。

举例如下:

~§

表示同一主版本号和次版本号中,不小于指定版本号的版本号。举例如下:

><=>=<=-§

用来指定一个版本号范围。举例如下:

注意使用 - 的时候,必须两边都有空格。

||§

表示或,举例如下:

xX*§

表示通配符,举例如下:

开发阶段的版本号§

开发阶段的版本号有一些例外:

^~ 表示同一个意思:主版本号和次版本号都相同,不小于指定版本号。举例如下:

先行版本号§

先行版本号也有一些例外:

只有以下几种方式可以匹配到先行版本号:

  1. 精确的指定版本号,如:1.0.0-alpha.1
  2. 使用 > 指定范围,如:>1.0.0-alpha>=1.0.0-rc.0 <1.0.1
  3. 使用 xX* 指定所有版本号,如:*

版本编译信息§

版本编译信息在判断匹配版本号的时候会被忽略,举例如下:

本文参考的版本§

本文书写时(2015-04-14),参考的版本号分别为:

若将来版本更新后有变,本文以以上版本号为准。