还在手动发包? 试试release-it 自动发包吧📦

Git►工程化►npm , 评论

前言

作为一名合格的前(摸鱼)工程师，日常工作开发中或多或少都要和npm包打交道。之前工作中就有过发布npm包的经历，但那时年少无知，只知道无脑通过npm publish发包，也没有打 tag、版本、没生成 changelog的概念。直到看到源码共读中有自动发包章节，还可以自动打tag等功能，赶紧收藏学习起来。

前置准备

要在npm上发包，当然需要在npm上注册账号，这个就不再赘述。我们在注册完账号之后，先设置一下镜像源，再登录自己的npm账号。如果有同学和我一样，使用的是公司内部私有的npm服务器，使用的账号和镜像源都是公司提供的，不要弄混淆，下面我们开始具体步骤。

准备项目文件

首先创建一个文件夹，然后执行npm init -y 初始化我们的项目

image.png

设置镜像源

如果是在已有项目中接入，最好要查看一下当前项目镜像源，初始化项目可以跳过。

那为什么要设置镜像源呢？装过npm包的同学都知道，npm官方public仓库是部署在国外，使用官方镜像源装包速度很慢，所以我们有时候会将镜像源设置为https://registry.npm.taobao.org，也就是淘宝镜像。这个时候如果我们使用npm的账号是无法登录的，或者是说你把镜像设置为公司内部私有的镜像源，这个时候通过官方npm账号也是无法登录的，曾经我就在这里踩过坑。在哪注册的账号，需要将镜像源设置为注册地的仓库。这里我们使用npm官方镜像源，将镜像源设置为https://registry.npmjs.org

1
2
3
4
5
# 查看当前镜像源
npm config get registry  

# 设置镜像源
npm set registry https://registry.npmjs.org

另外一种设置镜像源方式，可以在项目根目录中新建.npmrc文件

1
registry = https://registry.npmjs.org/

登录npm

使用npm注册的账号密码登录

1
2
3
4
5
6
7
8
9
10
11
# 登录
npm login

➜ npm login
Username: 用户名
Password: 密码
Email: 注册邮箱
Enter one-time password: 一次性密码  邮箱会收到邮件

➜ npm whoami 
# 查看当前登录账号名称

image.png

自动发包

release-it 官网仓库

release-it它做了什么？

  • 同步提交git远端内容
  • 更新版本号
  • 产出changelog
  • 提交变动
  • 增加git tag
  • 推送tag更新至远端

我们可以通过--dry-run可以看到具体进行了哪些操作

自动发包

安装

1
2
3
4
5
➜ npm init release-it
npx: 30 安装成功，用时 5.813 秒
? Where to add the release-it config? ›
❯   .release-it.json
    package.json

or

1
➜ npm install -D release-it

添加命令

1
2
3
"scripts": {
   "release": "release-it"
 },

配置

在项目根目录创建文件

  • .release-it.json
  • .release-it.js
  • .release-it.yaml
  • .release-it.toml

或者是在pakcage.json文件中添加release-it属性，这里我就直接创建.release-it.json文件，添加以下配置或者可以查看
更多配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "github": {
    "release": true
  },
  "git": {
    "commitMessage": "release: v${version}"
  },
  "npm": {
    "publish": true
  },
  "hooks": {
    "after:bump": "echo 更新版本成功"
  },
}

生成CHANGELOG

安装插件

1
➜ npm i @release-it/conventional-changelog -D

然后将以下内容添加到.release-it.json文件中

1
2
3
4
5
6
7
8
{
  "plugins": {
    "@release-it/conventional-changelog": {
      "preset": "angular",
      "infile": "CHANGELOG.md"
    }
  }

自动发布

运行命令，就可以进行发布

1
2
3
➜ npm run release
# or
➜ npx release-it

将release-it参数放在--后面

1
npm run release --minor --ci

发布其他版本

npm版本号

这里先初步补充一下npm版本号相关知识，npm的版本号遵循SemVer 规范，版本号格式必须采用X.Y.Z的格式，其中 X、Y 和 Z 为非负的整数。X 是主版本号、Y 是次版本号、而 Z 为修订号，英文对应表示为 major、minor、patch，每个号必须采用递增。

1
2
X.Y.Z ===> {major}.{minor}.{patch}
2.4.1

这种格式都是正式版，而在正式版发布之前还会经历各种先行版本，先行版本号会在原有的基础上增加一个版本号标签，先行版本格式是在修订版本patch号后面加上一个-连接，再通过.进行分割

1
2
# 格式
major.minor.patch-{identifier}.{identifier}.{identifier}

通常第一个 identifier 为版本号标签，后面则是自增版本号。
常用的版本号标签有

  • alpha内部测试版
  • beta公开测试版
  • rc候选版本

发布先行版本

理解完npm版本号相关知识后，那如何发布alpha、beta、rc版本呢？

我们可以看一下pre-releases ，就是通过不同的命令去创建发布不同的版本，比如我现在需要发布beta版本，就可以执行一下命令。

1
2
3
4
5
6
7
8
➜ npx release-it major --preRelease=beta
# 实际执行了三步
# 1.版本号从 0.2.0 更新至 1.0.0-beta.0
# 2.npm发布版本会打上beta标签，可以通过 npm i xxxx@beta 安装
# 3.github release会打上pre-release标识

# 综合起来就是
release-it premajor --preReleaseId=beta --npm.tag=beta --github.preRelease
  • beta可以换成"alpha", "beta", "rc"
  • major可以替换成major、minor、patch

预发布版本在更改的过程中，原有的先行版本号会清零。比如我从1.2.1-alpha.4升级到beta版本，就会变成1.2.1-beta.0

升级版本时，会将预发布版本清空，此时版本号不会变动。比如我上一个版本是3.0.0-rc.2，当我直接升级patch号就会变成3.0.0

升级当前预发布版本

1
➜ npx release-it --preRelease

将alpha版本修改为beta版本

1
➜ npx release-it --preRelease=beta

升级major、minor、patch版本号

1
➜ npx release-it major/minor/patch

当我们发布完后，需要使用到预发布版本依赖事，安装包的时候包名后面要带上@beta或者是其他版本

1
npm install release-it-test-wakaka@beta -D

我们也可以将命令拆分开来使用

1
2
3
4
5
6
7
8
# 只响应package.json中的版本号
$ npx release-it major --preReleaseId=beta

# 设置npm发版时的标识为beta
$ npx release-it major --npm.tag=beta

# 设置github release为预发布
$ npx release-it major --github.preRelease

查看包

我们发布完之后，如何查看自己是否发布成功呢？有以下几种方式

npm官网查看

可以在npm官网上直接搜索包的名字，或者是登录账号后在packages中查看自己发布的包

image.png

在versions中可以看到历史的版本

使用npm view命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 查看某个 package 的注册信息

npm view <package-name>

# 查看某个 package 的最新版本

npm view <package-name> version

# 查看某个 package 在 npm 服务器上所发布过的版本

npm view <package-name> versions

# 查看仓库依赖树上所有包的版本信息

npm ls

image.png

直接安装

简单粗暴，直接通过npm install <package-name>安装一下包，如果发布成功，安装时最好另起项目，不要在当前包项目中安装。

image.png

踩坑

包名重复

发包前，最好确认一下包名有没有重复，如果包名重复是无法发布的。校验包名最简单的办法就是去npm官网上搜你需要发布的名字，如果有就需要换一个名字，没有就可以发布。

错误的包名，无法发布
image.png

修改后，发布成功

image.png

没有git仓库提交代码

在安装完@release-it/conventional-changelog后，如果没有在git远程仓库提交代码，也是会发布失败
image.png

添加远程仓库后

image.png

当我们改完代码后，需要进行提交。

1
2
3
git add .
git commit -m 'xxxxx'
git push

changelog文件没有commit信息

为什么我提交了commit，但是生成的changelog中没有commit信息？

这是因为提交的commit信息不符合angular规范，在.release-it.json文件中我们可以看到

1
2
3
4
5
6
7
8
...
  "plugins": {
    "@release-it/conventional-changelog": {
      "preset": "angular",
      "infile": "CHANGELOG.md"
    }
  }
...

只要提交的规范符合angular规范，就可以了。

image.png

约定式提交

Angular提交信息规范

@release-it/conventional-changelog

总结

release-it使用下来，发现它帮我们节省了很多时间，整体发包流程都很规范。之前工作中进行发包的时候，直接一个npm publish就完事，也没有考虑到打tag、生成changelog这些事情。还有更多扩展性功能等待发现，比如配合上commitizen等工具，自定义commit信息，让changelog内容更丰富。配合git hooks，执行其他的一些操作。

同类型的产品还有standard-version，也是提供自动化发包流程，但整体来说还是release-it更灵活一些。

参考文章

package.json 配置完全解读

图文结合简单易学的npm 包的发布流程

聊聊 npm 的语义化版本（Semver）
自动产出changelog-第二节：自动产出

wakaka378a Vuer

我很懒，啥也没有