最详细的 lerna 中文手册

·  阅读 3823
最详细的 lerna 中文手册

携手创作,共同成长!这是我参与「掘金日新计划 · 8 月更文挑战」的第 2 天,点击查看活动详情

一、背景

或许在开发多包的过程中,总会遇到多包的发布工作流问题,详细解释就是一个 npm 包,由多个 npm 相互依赖构成,发布 npm 包 1,对其有依赖的 npm 包 2 也要一同发布,那么怎么才能将这个发布工作流简单化呢?

实现在发布 npm 包 1 时,自动检测依赖 npm 包的其他包,并同时发布,更新版本。

答案大家都知晓,那便是使用多包管理工具 lerna。

但是 lerna 官方文档(lerna 中文文档)不齐全,学习成本甚高,本文欲打造一个最详细的 lerna 手册,帮助查阅指令,熟悉 lerna。

二、lerna 介绍

lerna 是一个优化使用 git 和 npm 管理多包存储库工作流的工具。

它具有以下功能:

  • 自动解决 packages 之间的依赖关系;
  • 通过 git 检测文件改动,自动发布;
  • 根据 git 提交记录,自动生成 CHANGELOG。

三、工作模式

lerna 支持 2 种工作模式,分别是默认模式-Locked modeIndependent mode

默认模式-Locked mode

每次发布,所有有改动的包自动更新版本号,所有包的版本一致,版本号维护在 lerna.json 的 version 中。

Independent mode

每次发布时,将提示每个已更改的包,以及其建议的版本号,每个 package 都有自己的版本号。

设置方式:

lerna init --independent
复制代码

或修改 lerna.json:

version: "independent"
复制代码

四、常用指令

1. lerna init

初始化一个 lerna 工程或者升级现有 lerna 项目到当前版本的 lerna。

lerna init
复制代码

执行成功后,目录下将会生成这样的目录结构。

 - packages(目录)
 - lerna.json(配置文件)
 - package.json(工程描述文件)
复制代码

2. lerna create

创建一个 package,指定包名,可指定包位置。

lerna create < name > [location]

lerna create package1
lerna create package1.1 packages/package1
复制代码

3. lerna add

为包添加依赖。

  • --dev devDependencies 替代 dependencies
  • --exact 安装准确版本,就是安装的包版本前面不带^, Eg: "^2.20.0" ➜ "2.20.0"
lerna add lodash packages/module-1
复制代码

4. lerna bootstrap

将本地包链接在一起并安装其余的包依赖项。

lerna bootstrap
复制代码

5. lerna list

列出所有的包。

lerna list
复制代码

6. lerna import

导入本地已经存在的包。

lerna import [npm 包所在路径]
复制代码

7. lerna link

项目包建立软链,类似 npm link。

lerna link
复制代码

8. lerna clean

删除所有包的 node_modules 目录。

lerna clean
复制代码

9. lerna changed

列出自上次更改后已更改的本地包。

lerna changed
复制代码

10. lerna publish

发布包。

lerna publish
复制代码

11. lerna diff

区分自上次发布以来的所有包或单个包

lerna diff
复制代码

12. lerna info

打印有关本地环境的调试信息。

lerna info
复制代码

13. lerna run

在包含该脚本的每个包中运行 npm 脚本。

lerna run dev
复制代码

在包含该脚本的指定包中运行 npm 脚本。

lerna run dev --scope=packageA
复制代码

14. lerna version

更新版本。

lerna version
复制代码

五、lerna + yarn workspaces 实践

1. 安装

npm install lerna -g
复制代码

2. 创建项目

mkdir lerna-demo
复制代码

3. 初始化项目

cd ./lerna-demo
lerna init
复制代码

其中 package.json & lerna.json 如下:

// package.json
{
  "name": "root",
  "private": true, // 私有的,不会被发布,是管理整个项目,与要发布到npm的解耦
  "devDependencies": {
    "lerna": "^4.0.0"
  }
}

// lerna.json
{
  "packages": [
    "packages/*"
  ],
  "version": "0.0.0"
}
复制代码

4. 启用 yarn workspaces

各个库之间存在依赖,如 A 依赖于 B,因此我们通常需要将 B link 到 A 的 node_module 里,一旦仓库很多的话,手动的管理这些 link 操作负担很大,因此需要自动化的 link 操作,按照拓扑排序将各个依赖进行 link。

启用 yarn workspaces 可以把所有的依赖提升到顶层的 node_modules 中,并且在 node_modules 中链接到本地的 package,自动的帮忙解决安装和 link 问题。

修改 package.json:

{
    "private": true, // 只有私有项目可以开启
    "workspaces": ["packages/*"]
}
复制代码

修改 lerna.json:

{
    "useWorkspaces": true,
    "npmClient": "yarn"
}
复制代码

5. 添加 package

lerna create packageA
lerna create packageB
复制代码

6. 添加、删除、清除包依赖

yarn workspaces 添加依赖:

# 将packageA作为packageB的依赖进行安装:
$ yarn workspace packageB add packageA
# 给所有的package安装依赖:
$ yarn workspaces add lodash
# 给root 安装依赖:
$ yarn add -W -D typescript
复制代码

yarn workspaces 删除依赖:

# 删除packageB的依赖packageA:
$ yarn workspace packageB remove packageA
# 给所有的packages删除依赖:
$ yarn workspaces remove lodash
# 给root 删除依赖:
$ yarn remove -W -D typescript
复制代码

yarn workspaces 安装全部依赖:

yarn install
复制代码

yarn install 等价于 lerna bootstrap --npm-client yarn --use-workspaces,把所有的依赖提升到顶层的 node_modules 中,并且在 node_modules 中链接到本地的 package,自动的帮忙解决安装和 link 问题。

yarn workspaces 清除 node_modules:

yarn workspaces run clean
复制代码

7. 项目构建

构建所有包:

区别于普通项目之处在于各个 package 之间存在相互依赖,如 packageB 只有在 packageA 构建完之后才能进行构建,否则就会出错,这实际上要求我们以一种拓扑排序的规则进行构建。

lerna 支持按照拓扑排序规则执行命令, --sort 参数可以控制以拓扑排序规则执行命令。

# 以拓扑排序规则在包含该脚本的每个包中运行 npm run dev 脚本。
lerna run dev --stream --sort
# 以拓扑排序规则在包含该脚本的每个包中运行 npm run build 脚本。
lerna run build --stream --sort
复制代码

构建指定包:

# 在 packageA 包中运行 npm run dev 脚本。
lerna run dev --stream --scope=packageA
# 在 packageA 包中运行 npm run build 脚本。
lerna run build --stream --scope=packageA
复制代码

8. 发布

lerna publish
复制代码

发布指令 lerna publish 内置以下步骤:

  • 条件验证:包含验证测试是否通过,是否存在未提交的代码,是否在主分支上进行版本发布操作等等条件验证;

  • version_bump:发版的时候需要更新版本号,这时候如何更新版本号就是个问题,一般大家都会遵循  semVer 语义;

  • 生成 changelog:为了方便查看每个 package 每个版本解决了哪些功能,我们需要给每个 package 都生成一份 changelog 方便用户查看各个版本的功能变化;

  • 生成 git tag:为了方便后续回滚问题及问题排查通常需要给每个版本创建一个 git tag;

  • git 发布版本:每次发版我们都需要单独生成一个 commit 记录来标记 milestone;

  • 发布 npm 包:发布完 git 后我们还需要将更新的版本发布到 npm 上,以便外部用户使用。

小结

本文从 5 个方面介绍了 lerna:

  • 背景
  • 介绍
  • 工作模式
  • 常用指令
  • lerna + yarn workspaces 实践

相信你已经很熟悉 lerna 的使用了,下方还列举了参考资料,可以自行扩展阅读。

希望能对你有所帮助,感谢阅读~

别忘了点个赞鼓励一下我哦,笔芯 ❤️

参考资料

收藏成功!
已添加到「」, 点击更改