本文开始介绍了 npm 中语义化版本号的格式,然后对如何升级版本号进行了归纳,最后总结了如何正确的定义依赖的版本号。
认识 npm 版本号§
每一个 node package 都有自己的版本号,一般定义在项目的 package.json
中,如:
{
"name": "express",
"description": "Fast, unopinionated, minimalist web framework",
"version": "4.12.3",
"author": "TJ Holowaychuk <tj@vision-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
另外,以下列出了一些常见的先行版本号名称:
alpha
beta
rc
版本编译信息(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 有了一些拓展:
- 允许版本号中大于零的数字以零开头
- 允许以
v
开头 - 允许以
=
开头 - 允许
v
或=
与版本号之间有空字符串 - 允许在开头包含空字符串
- 上面四个规则中,
v
、=
和空字符串都允许出现多次
更深入的讲,node-semver 提供了两种模式,普通模式和宽松模式,普通模式包含了上面 2 的拓展,宽松模式包含了以上所有拓展。
具体内容可以阅读源码了解。
如何升级版本号§
升级版本号的规则主要有三个:
- 主版本号:当你做了不兼容的 API 修改
- 次版本号:当你做了向下兼容的功能性新增
- 修订号:当你做了向下兼容的问题修正
开发阶段的版本号§
主版本号为零的时候,属于开发阶段,一切都可能随时改变,故以上三个规则也不一定适用。
一般来说,修订号的修改仍然保持向下兼容,但是次版本号就不一定向下兼容了。
先行版本号§
先行版本号一般用于发布一个新的主版本号(比如 1.0.0
、2.0.0
、3.0.0
)之前,同样是不一定兼容的。
另一些的规则§
- 任何时候都禁止修改已发布的版本的内容,任何修改都必须以新版本发布
- 次版本号的升级,必须把修订号归零
- 主版本号的升级,必须把次版本号和修订号归零
如何正确的定义依赖的版本号§
在 node package 中,经常需要依赖一些 npmjs.com 上的资源,使用 npm install express --save
或 npm install express --save-dev
即可在安装的同时,把依赖关系写入 package.json
的 dependencies
或 devDependencies
中。
"dependencies": {
"express": "^4.12.3"
},
默认会在版本号前面加上一个 ^
,在 npm 的依赖的规则中,还有 ~
、>
、<
、=
、>=
、<=
、-
、||
、x
、X
、*
等符号,下面会一一解释。
^
§
表示同一主版本号中,不小于指定版本号的版本号。
举例如下:
^2.2.1
对应主版本号为 2,不小于2.2.1
的版本号,比如2.2.1
、2.2.2
、2.3.0
~
§
表示同一主版本号和次版本号中,不小于指定版本号的版本号。举例如下:
~2.2.1
对应主版本号为 2,次版本号为 2,不小于2.2.1
的版本号,比如2.2.1、2.2.2
>
、<
、=
、>=
、<=
、-
§
用来指定一个版本号范围。举例如下:
>2.1
1.0.0 - 1.2.0
注意使用 -
的时候,必须两边都有空格。
||
§
表示或,举例如下:
^2 <2.2 || > 2.3
x
、X
、*
§
表示通配符,举例如下:
*
对应所有版本号3.x
对应所有主版本号为 3 的版本号
开发阶段的版本号§
开发阶段的版本号有一些例外:
^
和 ~
表示同一个意思:主版本号和次版本号都相同,不小于指定版本号。举例如下:
^0.1.0
对应主版本号为 0,次版本号为 1,不小于0.1.0
的版本号,比如0.1.0
,0.1.1
先行版本号§
先行版本号也有一些例外:
只有以下几种方式可以匹配到先行版本号:
- 精确的指定版本号,如:
1.0.0-alpha.1
- 使用
>
指定范围,如:>1.0.0-alpha
、>=1.0.0-rc.0 <1.0.1
- 使用
x
、X
、*
指定所有版本号,如:*
版本编译信息§
版本编译信息在判断匹配版本号的时候会被忽略,举例如下:
3.0.2+20130313144700
会匹配到3.0.2
本文参考的版本§
本文书写时(2015-04-14),参考的版本号分别为:
若将来版本更新后有变,本文以以上版本号为准。