头图

聊聊 npm 的语义化版本(Semver)

前言

现在我们要开发一个项目,我们都知道为了方便项目管理,要写一个版本号,那开发的时候初始的版本号是多少呢?是 1.0.0 还是 0.0.1 开始?

如果一个版本号为 X.Y.Z,什么时候是 X 应该加 1,什么时候 Y 应该加 1 ,什么时候 Z 应该加 1,加 1 遵循十进制吗?比如 1.0.9 的下一个版本应该是 1.1.0 吗?

我们经常看到一些项目的版本还带着后缀,比如 React 的 18.0.0-rc.3、 Vue 的 2.7.0-alpha.12,这些又是什么意思呢?这些后缀是固定字段还是可以自定义的呢?

SemVer 规范

实际上,语义化的版本控制并不是一个创新性的想法,即便我们不知道这些,我们也在做类似的事情,但一个明确的规范将会让版本逻辑更清晰的传达给其他开发者。

所以由 Gravatars 创办者兼 GitHub 共同创办者 Tom Preston-Werner 就建立了语义化版本控制的规范, semantic version 简称 semver,于是这个规范就叫做 SemVer 规范,规范地址为:https://semver.org/lang/zh-CN/

我简单讲讲其中的内容,大家也很容易理解:

版本号的格式

标准的版本号必须采用 X.Y.Z 的格式,其中 X、Y 和 Z 为非负的整数,且禁止在数字前方补零。X 是主版本号、Y 是次版本号、而 Z 为修订号,英文对应表示为 major、minor、patch,每个元素必须以数值来递增。例如:1.9.1 -> 1.10.0 -> 1.11.0。

主版本号为零(0.y.z)的软件处于开发初始阶段,一切都可能随时被改变。

1.0.0 的版本号用于界定公共 API 的形成。

版本号的递增逻辑

修订号 Z(x.y.Z | x > 0)必须在只做了向下兼容的修正时才递增。这里的修正指的是针对不正确结果而进行的内部修改。

次版本号 Y(x.Y.z | x > 0)必须在有向下兼容的新功能出现时递增。在任何公共 API 的功能被标记为弃用时也必须递增。也可以在内部程序有大量新功能或改进被加入时递增,其中可以包括修订级别的改变。每当次版本号递增时,修订号必须归零。

主版本号 X(X.y.z | X > 0)必须在有任何不兼容的修改被加入公共 API 时递增。其中可以包括次版本号及修订级别的改变。每当主版本号递增时,次版本号和修订号必须归零。

简单的总结下就是:

  1. 当有不兼容的 API 更改时,则升级主版本号
  2. 当以向后兼容的方式添加功能时,则升级次版本号
  3. 当进行向后兼容的缺陷修复时,则升级修订号

关于先行版本

先行版本号可以被标注在修订版之后,先加上一个连接号再加上一连串以句点分隔的标识符来修饰。标识符必须由 ASCII 字母数字和连接号组成,且禁止留白。数字型的标识符禁止在前方补零,举个例子:1.0.0-alpha.6

先行版的优先级低于相关联的标准版本,举个例子 1.0.0-alpha < 1.0.0

被标上先行版本号则表示这个版本并非稳定而且可能无法满足预期的兼容性需求。

问题回答

其实规范内容并不多,回到开头时的第一个问题:

Q:在 0.y.z 初始开发阶段,我该如何进行版本控制?
A:最简单的做法是以 0.1.0 作为你的初始化开发版本,并在后续的每次发行时递增次版本号。

Q:如何判断发布 1.0.0 版本的时机?
A:当你的软件被用于正式环境,它应该已经达到了 1.0.0 版。如果你已经有个稳定的 API 被使用者依赖,也会是 1.0.0 版。如果你很担心向下兼容的问题,也应该算是 1.0.0 版了。

alpha beta 和 rc

现在我们知道,先行版本中 - 后的字符是自定义的,我们经常看到一些库的版本会带 alpha、beta 之类的字样,就以 Vue 为例,有 3.0.0-alpha.133.0.0-beta.13.0.0-rc.1,这些表示什么意思呢?

一般来说:

alpha 表示内部测试版,主要给开发和测试找 bug 用,不建议用户下载
beta 表示公开测试版,你可以提前尝试一些功能
rc 是 Release Candidate(候选版本)的缩写,表示该版本功能不再增加,和最终发布版功能一样,有点像预览版,然后可能再改改一些小 bug,就会到正式的版本了。

当然库也可以使用自己的版本逻辑,就比如 React,它还有 next 版和 experimental 版,具体的发布逻辑 React 官网也有写: https://react.docschina.org/docs/release-channels.html

npm 指定版本范围

我们经常在 package.json 文件中看到版本号前出现 ~ ^ 等字符,比如:

{
   "dependencies": {
    "react": "^1.2.3
    "vue": "~1.2.3",
  }
}

这些标识符的作用相信我们多少都知道一点,比如:

^ 表示次版本号的更新,比如 ^1.2.3就表示以后安装的版本 >=1.2.3 <2.0.0
~ 表示修订版本号的更新,比如 ~1.2.3就表示以后安装的版本 >=1.2.3 <1.3.0

当然具体的逻辑会更复杂一点,比如:

^只会执行不更改最左边非零数字的更新,所以:

  1. ^0.2.3 相当于 >=1.2.3 <2.0.0
  2. ^0.0.3相当于>=0.0.3 <0.0.4
  3. ^1.2.3-beta.2 相当于 >=1.2.3-beta.2 <2.0.0,这其中 1.2.3-beta.4是可以的,但 1.2.4-beta.2就不行了

    ~如果指定了次版本号,则会只进行修订版本号的更新,如果没有指定,则会进行此版本号的更新,所以:

  4. ~1.2.3 相当于 >=1.2.3 <1.3.0
  5. ~1.2相当于 >=1.2.0 <1.3.0 (相当于 1.2.x)
  6. ~1 相当于 >=1.0.0 <2.0.0 (相当于 1.x)
  7. ~1.2.3-beta.2 相当于 >=1.2.3-beta.2 <1.3.0,这其中 1.2.3-beta.4是可以的,但 1.2.4-beta.2就不行了

除了 ^~,NPM 提供了更多的表示范围版本的方式:https://docs.npmjs.com/cli/v8/configuring-npm/package-json#dependencies

简单举几个示例:

{
  "dependencies": {
    "foo": "1.0.0 - 2.9999.9999",
    "bar": ">=1.0.2 <2.1.2",
    "baz": ">1.0.2 <=2.3.4",
    "qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
    "lat": "latest",
  }
}

这其中 latest 表示标签,在默认情况下,npm 使用 latest 标签来标识软件包的当前版本。

对应我们安装包的时候也可以参照这些指定版本安装:

npm install foo@1.2.3
npm install foo@">=0.1.0 <0.2.0"
npm install foo@latest

npm version

NPM 也提供了 npm version 命令可以更新版本号,具体的语法如下:

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

其中最主要的就是 majorminorpatch,比如你当下的项目的 package.jsonversion1.0.0

当你执行 npm version major 后,version 会变成 2.0.0
当你执行 npm version minor后,version 会变成 1.1.0
当你执行 npm version patch 后,version 会变成 1.0.1

premajorpreminorprepatch 也是同理:

当你执行 npm version premajor后,version 会变成 2.0.0-0
当你执行 npm version premajor后,version 会变成 1.1.0-0
当你执行 npm version prepatch后,version 会变成 1.0.1-0

而当你执行 npm version prerelease后,version 也会变成 1.0.1-0

prepatchprerelase 的区别在于,prepatch 是增加 patch 号,先行版本号置为 0,prerelase 则是如果没有先行版本号,则跟 prepatch 一样,如果有的话,则会在先行版本号上加 1,举个例子,当你的版本号为 1.0.0-0时,

当你执行 npm version prepatch后,version 会变成 1.0.1-0
而当你执行 npm version prerelease后,version 会变成 1.0.0-1

你也可以在此基础上再添加一个 -m 参数:

npm version patch -m "Upgrade to %s for reasons"

其中 %s 表示新的版本号,npm 会创建一个 commit 信息,就相当于 npm 修改了版本号后,又对文件执行了一句 git commit -am "Upgrade to %s for reasons"

更多 npm version 命令可以参考 npm 官方文档 https://docs.npmjs.com/cli/v8/commands/npm-version

系列文章

冴羽答读者问全目录:https://github.com/mqyqingfen...

如果喜欢或者有所启发,欢迎 star,对作者也是一种鼓励。


冴羽的JavaScript博客
冴羽写JS文章的地方,预计写四个系列:JavaScript深入系列、JavaScript专题系列 、ES6系列、React系列。

17 年开始写前端文章,至今 6 个系列,上百篇文章,全网千万阅读

9.2k 声望
6.2k 粉丝
0 条评论
推荐阅读
React 之 Context 的变迁与背后实现
本篇我们讲 Context,Context 可以实现跨组件传递数据,大部分的时候并无需要,但有的时候,比如用户设置 了 UI 主题、地区偏好,如果从顶层一层层往下传反而有些麻烦,不如直接借助 Context 实现数据传递。

冴羽1阅读 1.2k

封面图
从零搭建 Node.js 企业级 Web 服务器(零):静态服务
过去 5 年,我前后在菜鸟网络和蚂蚁金服做开发工作,一方面支撑业务团队开发各类业务系统,另一方面在自己的技术团队做基础技术建设。期间借着 Node.js 的锋芒做了不少 Web 系统,有的至今生气蓬勃、有的早已夭折...

乌柏木140阅读 11.9k评论 10

从零搭建 Node.js 企业级 Web 服务器(十五):总结与展望
总结截止到本章 “从零搭建 Node.js 企业级 Web 服务器” 主题共计 16 章内容就更新完毕了,回顾第零章曾写道:搭建一个 Node.js 企业级 Web 服务器并非难事,只是必须做好几个关键事项这几件必须做好的关键事项就...

乌柏木60阅读 5.9k评论 16

再也不学AJAX了!(二)使用AJAX ① XMLHttpRequest
「再也不学 AJAX 了」是一个以 AJAX 为主题的系列文章,希望读者通过阅读本系列文章,能够对 AJAX 技术有更加深入的认识和理解,从此能够再也不用专门学习 AJAX。本篇文章为该系列的第二篇,最近更新于 2023 年 1...

libinfs39阅读 6.1k评论 12

封面图
从零搭建 Node.js 企业级 Web 服务器(一):接口与分层
分层规范从本章起,正式进入企业级 Web 服务器核心内容。通常,一块完整的业务逻辑是由视图层、控制层、服务层、模型层共同定义与实现的,如下图:从上至下,抽象层次逐渐加深。从下至上,业务细节逐渐清晰。视图...

乌柏木39阅读 7.1k评论 6

CSS 绘制一只思否猫
欢迎关注我的公众号:前端侦探练习 CSS 有一个比较有趣的方式,就是发挥想象,绘制各式各样的图案,比如来绘制一只思否猫?思否猫,SegmentFault 思否的吉祥物,是一只独一无二、特立独行、热爱自由的(&gt;^ω^&lt...

XboxYan41阅读 2.8k评论 14

封面图
还在用 JS 做节流吗?CSS 也可以防止按钮重复点击
举个例子:一个保存按钮,为了避免重复提交或者服务器考虑,往往需要对点击行为做一定的限制,比如只允许每300ms提交一次,这时候我想大部分同学都会到网上直接拷贝一段throttle函数,或者直接引用lodash工具库

XboxYan34阅读 2.2k评论 2

封面图

17 年开始写前端文章,至今 6 个系列,上百篇文章,全网千万阅读

9.2k 声望
6.2k 粉丝
宣传栏