lerna + yarn workspace 使用总结

9,953 阅读16分钟

前言

大家好, 本文是笔者在学习和团队落地 lerna + yarn workspace 多包工程化管理模式的过程中,记录的一些使用技巧和问题汇总,作为笔记分享于大家阅读。

Monorepo 模式,有别于传统的 Multirepo 单仓库应用模式,下面我们先来了解一下两者的区别。

一、项目管理模式对比

1、Multirepo

传统的项目开发模式,比如 create-react-appvue-cli 等框架模板脚手架生成的项目。

  • 优点:
    1. 各模块管理自由度高;
    2. 各模块仓库体积一般不会太大;
  • 缺点:
    1. 仓库分散不好找,分支管理混乱;
    2. 版本更新频繁,公共模块版本发生变化,需要对所有模块进行依赖更新;

2、Monorepo

  • 优点:
    1. 统一的规范、构建工具;
    2. 方便版本管理和依赖,模块之间的引用调试都变得非常方便;
    3. Multirepo 的缺点就是它的优点。
  • 缺点:
    1. 随着应用扩展,仓库体积将变大。

二、Lerna

Lerna 是一个项目多包管理工具,用于管理包含多个软件包(package)的 JavaScript 项目,是 Babel 自己用来维护自己的 Monorepo 并开源出的一个项目。

它可以:

  • 统一的一套规范、构建标准;
  • 对相互耦合较大、相互独立的 JS/Git 库进行管理;
  • 统一的工作流和 Code Sharing(代码共享)。

下面我们从以下几个方面来认识 Lerna:

  • Lerna 管理模式;
  • Lerna 入门指引;
  • Lerna 管理命令;
  • Lerna 配置文件;
  • Lerna 应用Demo;
  • Lerna 版本发布;
  • Lerna 最佳实践;
  • Lerna 注意事项。

1、Lerna 管理模式

lerna 管理项目可以使用两种模式,默认固定模式,当使用 lerna init -i 命令初始化项目时,此时为独立模式。(模式是用来管理多个 package 发包时的方式)

  1. 固定模式: 在发包时会检测 packages 下涉及到变更的包,给这些变更的包使用同一版本,未发生变更的包不应用改版本,且不做发布升级;发布时可通过 lerna publish major(大) | minor(中) | patch (小)自定义版本。

  2. 独立模式(常用的模式): 允许每个包有自己独立的版本号,在 lerna publish 发布时,需要为每个改动的库指定版本号(逐个询问需要升级的版本号)。此模式,lerna.json - version 字段指定为 independent。

如果 packages 下,其中一个包发生改动,另一个包依赖了这个包,即使它没有发生改动,也会被进行发布更新。

2、Lerna 入门指引

  1. 全局安装 Lerna:
npm install --global lerna
  1. 初始化 git 代码仓库:
git init lerna-repo && cd lerna-repo
  1. 初始化 Lerna:
lerna init
// lerna info Creating package.json 
// lerna info Creating lerna.json 
// lerna info Creating packages directory 
// lerna success Initialized Lerna files
  1. 此时得到了这样一个仓库目录结构:
lerna-repo/ 
    packages/ 
    package.json 
    lerna.json

其中 packages 中保存着每个独立的包模块。

  1. 安装 lerna 到仓库 node_modules 中:
npm install

至此,我们就完成了一个 Lerna 工程的初始化工作,下面我们掌握一些操作命令来管理 Lerna。

3、Lerna 管理命令

  1. lerna init

将一个仓库初始化为 lerna 仓库(默认固定模式)。

支持参数:

  • --independent/-i:使用独立的版本控制模式
lerna init -i
  1. lerna create 「package」

创建一个 package 到项目工程的 packages 下。

lerna create package1
  1. lerna add 「module」
  • 为每个 package 都安装指定依赖:
lerna add react
  • 为指定的 package 安装特定依赖:
lerna add react-dom packages/package1 
// or 
lerna add react-dom --scope=package1
  • 添加依赖到根目录 node_modules 中:
npm install typescript -D
  • package 之间的相互依赖(会在 package/package.json 下添加该依赖):
lerna add package2 --scope package1 
// or 
lerna add package2 packages/package1
  1. lerna publish 用于 npm 包版本发布,具体细节可看下文 「Lerna 版本发布」。

  2. lerna bootstrap

用于将 packages 链接在一起(前提是相互依赖的库),并安装 package 下的依赖到 package/node_modules。

注意,它不会安装根目录 package.json 的依赖,如果需要安装根目录依赖,请使用 npm install。

参数:

  • --hoist:依赖提升,把每个 package 下的依赖包都提升到工程根目录(删除包下的 node_modules,将依赖安装在根目录,但依赖注册不会在 package/package.json 内删除,也不会在 root/package.json 内添加此依赖)
  1. lerna clean 删除各个包下的 node_modules(不会删除根目录 node_modules)。

  2. lerna ls 列出当前 Lerna 仓库中的所有公共软件包(public packages)。

  3. lerna run 「script」

  • 运行每个包下面的 script(如果某个包没有此 script,将会报错)
lerna run test
  • 运行某个包下面的 script
lerna run test --scope package1
  1. lerna exec 「shell」 允许去执行 shell 脚本
lerna exec webpack
  1. lerna changed 检查自上次发布以来哪些软件包被修改过。

  2. lerna link 链接互相引用的库,当 pakcage/package.json 内明确了 packages 下的包时,才会将相关包链接到 package/node_modules 中。

  3. lerna info 查看 lerna 及运行环境的信息。

4、Lerna 配置文件

在 lerna.json 配置文件内可以指定工作模式、packages 的位置以及一些命令的默认参数定义,如下示例:

{
  "version": "1.0.0",
  "npmClient": "yarn",
  "useWorkspaces": true,
  "packages": [
    "packages/*"
  ],
  "command": {
    "bootstrap": {
      "npmClientArgs": [
        "--no-package-lock"
      ]
    },
    "version": {},
    "publish": {
      "npmClient": "npm",
      "ignoreChanges": [
        "**/*.md",
        "**/test/**"
      ],
      "message": "chore(release): publish",
      "registry": "https://registry.npmjs.org",
      "conventionalCommits": true
    }
  }
}
  • version: 当前仓库的版本,Independent mode 请设置为 independent;

  • packages: 指定包所在的目录,支持指定多个目录;

  • npmClient: 允许指定命令使用的client, 默认是 npm, 可以设置成 yarn;

  • useWorkspaces: 使用 yarn workspaces 管理 Monorepo;

  • command.bootstrap.npmClientArgs: 指定默认传给 lerna bootstrap 命令的参数;

  • command.publish.ignoreChanges: 指定那些目录或者文件的变更不用触发 package 版本的变更;

  • command.publish.message: 执行发布版本更新时的生成的 commit message;

  • command.publish.registry: 指定发布到的 registry url,比如可以发布到指定私服,默认是 npmjs.org;

  • command.publish.conventionalCommits: lerna version 将生成 CHANGELOG.md files(如果设置了这个,lerna 管理模式将直接使用固定模式,version = independent 的配置将失效)。

5、从 Demo 入门 Lerna

现在我们对 lerna 有了基本认识,下面我们通过一个简单 Demo 熟悉一下 Lerna 管理 Packages 的流程方式。

  1. 创建 Lerna 工程:
git init lerna-demo && cd lerna-demo && lerna init
  1. 创建两个 package:
lerna create lerna-module1
lerna create lerna-module2
  1. 在 package 中添加几行测试代码:
// lerna-module1/lib/lerna-module1.js
module.exports = lernaModule1;
function lernaModule1() {
  console.log('lerna-module1');
}

// lerna-module2/lib/lerna-module2.js
const lernaModule1 = require('lerna-module1');
module.exports = lernaModule2;
function lernaModule2() {
  console.log('lerna-module2');
}
lernaModule1();
lernaModule2();
  1. 在 lerna-module2 下添加一个执行脚本:
// lerna-module2/package.json
"scripts": {
  "test": "node ./lib/lerna-module2.js"
}
  1. 运行脚本:
lerna run test --scope lerna-module2

哎呀,此时会看到终端如下报错信息,原因是没有将 lerna-module1 关联到 lerna-module2 中。

Error: Cannot find module 'lerna-module1'

  1. 手动建立 package 之间的关联:
lerna add lerna-module1 --scope lerna-module2 
// lerna info Adding lerna-module1 in 1 package

此时可以在 lerna-module2 目录下看到生成了 node_modules 文件夹,并且在里面放置了和 lerna-module1 一模一样的包(软链接)。

  1. 再来执行一次命令:
lerna run test --scope lerna-module2 
终端输出: 
lerna-module1 
lerna-module2

好啦,我们第一个简单 Lerna 应用编写完成。接下来就是发布工作。

6、Lerna 版本发布

packages 下的包版本发布需要使用 lerna publish,这个命令组合了这两个命令:lerna versionnpm publish

其中 lerna version 针对 Lerna 的管理模式(固定模式和独立模式),在表现上有所不同。

但主要工作还是在进行 npm publish 之前,去管理哪些包要进行发布,以及发布过程中生成的 Git commit、Git tag 的提交。

  1. 固定模式下的 lerna version:
  • 找出从上一个版本发布以来有过变更的 package
  • 根据当前 lerna.json 中的版本生成新的版本号
  • 更新涉及到变更 package 下的 package.json 版本号;
  • 更新 lerna.json 文件中的版本号;
  • 将 version 更新、生成的 CHANGELOG.md 文件带来的变动提交为一次 commit
  • 基于这次 commit 为所有涉及到更新的 package 打上各自的 tag
  • 推送 commit 和 tags 到远程仓库。
  1. 独立模式下的 lerna version:
  • 找出从上一个版本发布以来有过变更的 package
  • 提示开发者为需要更新的 package 选择(一组 Version Select)要发布的版本号
  • 更新到 package 下的 package.json version 版本号
  • 如果 packages 下其他包有依赖这个包,那么这些包下的 package.json 中此包版本也会更新;
  • version 的更新变动提交为一次 commit
  • 基于这次 commit 为所有涉及到更新的 package 打上各自的 tag
  • 推送 commit 和 tags 到远程仓库。

这里需要注意一下 lerna 查找包变更的逻辑:

在当前分支,找到最近一次 tag,将当前 commit 和 tag 进行比较,看哪些 package 下的文件发生了变更。

命令使用如下:

lerna publish
lerna publish semver
// semver bump [major | minor | patch | premajor | preminor | prepatch | prerelease]
lerna publish from git
lerna publish from-package

初次使用发布时可能会遇到以下一些问题和注意事项:

  1. 避免开发者自己去打 tag。 lerna 发布时会自动生成 tag,并且查找更新是基于 tag 来识别的,避免开发者手动打上 tag 后,影响 lerna 查找变更,可能会造成一些变更包没有按照预期发布。

  2. 避免多条分支同时进行。 在多条分支同时进行时,可能会生成相同的版本号,从而发生版本冲突。解决办法:分支开发者之前应提前约定好版本。

  3. lerna publish 中途发布失败,如何进行重发布。 有时候发布可能会失败(比如 npm 没有登录、没有使用 npmjs 镜像源),再次运行 lerna publish 时,因为 tag 已经打上了,无法再查找到更新,进行包的发布。

可以采用下面两种发布方式:

  • 运行 lerna publish from-git。会将当前标签中涉及的NPM包再发布一次。(不会再更新package.json,只是执行npm publish);
  • 运行 lerna publish from-package。会将当前所有本地包中的 package.json 和远端 npm 比对,如果 npm 上不存在此包的最新版本,都执行一次 npm publish。

7、Lerna 最佳实践

目前业界使用最多的方案是:lerna + yarm workspace 结合的 Monorepo 方案,两者工作职责划分不同:

  • yarn 处理依赖管理工作(只想做好包管理工具);
  • lerna 处理发布流程。

此处内容可以在下文查看 yarn workspace 使用指南。

8、Lerna 注意事项

  1. 发布前,提交工作区的变更。 在发布前,需要提交工作区的文件变更,否则终端会收到下面报错信息:

lerna ERR! EUNCOMMIT Working tree has uncommitted changes, please commit or remove the following changes before continuing:

  1. 发布前,需使用 npmjs.org 镜像。 在发布前,如果 npm 设置的镜像源为淘宝镜像,需要切换回 npm 镜像:
npm config get registry
npm config set registry https://registry.npmjs.org
  1. 如果要发布一个 Scope 包: Scope 是指具有“组织”的包,比如 Babel 的相关包都是这一格式:@babel/xxx,在发布一个具有 Scope 包时,需要确保 Organization(组织)已在 npm 上创建,私有包需要收费,公共包则为免费。

在发布 Scope package 时,需要在 package.json 声明 access publish

{
  "name": "@feu/tools",
  "publishConfig": {
    "access": "publish"  // 如果该模块需要发布,对于 scope 模块,需要设置为 publish
   }
 }
  1. 发布意外中断,进行重发布: 如果发布因为某些原因中断了,未发布成功,再次执行发布,会得到如下提示:

lerna success No changed packages to publish

但由于包并未成功发布到 npmjs 上,这时可以执行以下命令进行重发布:

lerna publish from-git
// or
lerna publish from-package
  1. independent 模式并未生效: 在 lerna.json 下指定了 version 为 independent,但是发布时却还是固定模式的流程,原因可能是 lerna.json 内配置了 conventionalCommits
"command": {
  "publish": {
    "conventionalCommits": true
  }
}

可以将其配置移除得到解决。

  1. 固定模式如何自己指定版本: 当我们执行 lerna publish 时,lerna 会自定分配一个版本提供我们使用;但这个版本可能不是我们期望发布的版本;如何自己控制发布的版本呢,在发布时我们可以传递配置:
lerna publish major(大) | minor(中) | patch (小) 
lerna publish patch // 发布小版本

三、yarn workspace

对于 Monorepo 的工程,使用最多的方式是 lerna 结合 yarn workspace 一起使用。

因为 yarn 在依赖管理上做的非常不错,适合我们业务场景的依赖模块管理。

package 的发布工作依旧交由 lerna publish 来运转。

注意:yarn workspace 可以独立管理 Monorepo 项目,结合 lerna 可以提升对包版本管理和发布管理。

下面我们从以下几个方面来熟悉 yarn workspace 和 lerna 的使用:

  • yarn workspace 管理工程;
  • yarn workspace 管理命令;
  • yarn workspace 入门实战。

1、yarn workspace 管理工程

yarn workspace 可以独立使用来管理 Monorepo 项目。下面我们使用 yarn workspace 一步一步搭建一个多包管理工程。

  1. 初始化项目
yarn init -y
  1. 创建 packages 工作区目录,并创建两个子包:package-a 和 package-b
# 创建 packages 工作区目录
mkdir packages
# 创建 package-a 子包
cd packages && mkdir package-a && cd package-a && yarn init -y
# 创建 package-b 子包
cd packages && mkdir package-b && cd package-b && yarn init -y
  1. 在根目录 package.json 中配置工作区 workspaces 字段
{
  "name": "monorepo",
  "private": true, // 设置私有仓库,工作空间根目录不需要 npm 包发布
  "workspaces": [
    "packages/*"
  ]
}

现在,我们的 yarn workspace monorepo 项目初始化完成,接下来使用 yarn workspace 命令来管理包依赖。

2、yarn workspace 管理命令

yarn 管理命令大致分为两类(容易混淆,这里先提及一下):

  • 处理工程下指定的包模块时使用:yarn workspace
  • 处理工程根目录全局或所有包模块时使用:yarn workspaces

另外,执行以下命令时要在根目录路径下执行。

1、yarn install

安装全部依赖。yarn install 会将 package 下的依赖统一安装到根目录之下。这有利于提升依赖的安装效率和不同 package 间的版本复用(有些包是需要私有依赖的,而私有依赖会被多个包安装多次,而提升依赖可以解决这一问题)。

2、yarn add 「module」

  • 1)安装依赖到根目录下

在使用 yarn add 安装依赖命令时,-W 参数表示将依赖添加到 workspaces 根目录。

yarn add react -W 

安装成功后,根目录下 package.json 文件中会看到 react 依赖项。

  • 2)为工作区指定的 package 安装依赖:
yarn workspace package-a add react-dom

安装成功后,package-a 的 package.json 中会有 react-dom 依赖项,且 react-dom 依赖包代码会安装到根目录下的 node_modules 中,不会在 package-a 中产生 node_modules 目录。(如果根目录 node_modules 中存在一个相同包但版本不同,这时会放入 package-a 的 node_modules 目录下

注意,package-a 一定是 packages/package-a/package.json name 字段,若 package 的目录名和 name 字段不一致,要以 name 为准。

  • 3)工作区的 package 之间的相互依赖(会在 package/package.json 下添加该依赖):

如在 package-a 包中将 package-b 作为依赖包安装和使用。

yarn workspace package-a add package-b@^1.0.0

注意,安装时一定要指定工作区的包版本,否则会在 npmjs 上查找包,而不是安装工作区的包。包之间的相互依赖,个人觉得 pnpm monorepo 做的比较好,它有 workspace: 协议。

  • 4)在工程根目录下引入 packages/package 包:
yarn add package-a@^1.0.0 -W

安装成功后,根目录下 package.json 文件中会看到 package-a 依赖项。

3、yarn remove「module」

和上面 yarn add 命令格式相同,只需将 add 替换为 remove 即可。

yarn remove react -W

yarn workspace package-a remove react-dom

4、yarn run 「script」

  • 1)运行工程根目录下 script
yarn test
  • 2)运行指定包模块下的 script
yarn workspace package-a run test

需要注意的是,当命令执行的是一个 JS 文件时,并在文件中打印 process.cwd()(NodeJS 进程当前工作的目录),得到的路径其实是 /.../packages/package-a 目录,即为当前运行的包的所在路径。命令虽然是在根目录下执行,但 process.cwd() 不会指向根路径。
这在使用共享配置时,通过 process.cwd() 可以知道是来自哪个包的使用。

  • 3)运行所有 package 下的 script 命令:
yarn workspaces run test

注意,如果某个 package 下没有对应 script,将会终止命令,并报错。若 package 不具备 script,可以定义一个占位 script,类似如下:

"scripts": {
  "lint": "echo lint successful."
}

5、yarn workspaces info

查看 workspace 工作区包的依赖树信息。

3、yarn workspace 结合 lerna

初始化工程的步骤和上面 lerna 的方式一样,与 lerna 不同的是,需要做以下配置:

lerna.json 中声明使用 yarn workspace 进行依赖管理:

{
  ...
  "npmClient": "yarn",
  "useWorkspaces": true
}

4、yarn workspace + lerna 入门实战

  1. 新建 yarn workspace 工程:
git init yarn-demo && cd yarn-demo && yarn init -y && yarn add lerna -D && lerna init
  1. 配置 lerna.json 改用 yarn workspaces:
// lerna.json
{
  "npmClient": "yarn",
  "useWorkspaces": true,
  "packages": [
    "packages/*"
  ],
  "version": "independent"
}
  1. 根目录 package.json 必须包含一个 workspaces 数组:
{
  "private": true, // 设置私有仓库,工作空间根目录不需要 npm 包发布
  "workspaces": ["packages/*"],
  ...
}
  1. 新建两个 package:
cd packages && mkdir yarn-module1 && cd yarn-module1 && yarn init -y
cd packages && mkdir yarn-module2 && cd yarn-module2 && yarn init -y
  1. 添加几行测试代码:
// yarn-module1/index.js
function yarnModule1() {
  console.log('yarn-module1');
}

module.exports = yarnModule1;

// yarn-module2/index.js
const yarnModule1 = require('yarn-module1');

function yarnModule2() {
  console.log('yarn-module2');
}

yarnModule1();
yarnModule2();

module.exports = yarnModule2;
  1. 为 yarn-module2 添加个 script:
// yarn-module2/package.json
"scripts": {
  "test": "node index.js"
}
  1. 回到根目录执行 script:
yarn workspace yarn-module2 run test

不出意外,会得到如下错误:

Error: Cannot find module 'yarn-module1'

  1. 建立 package 之间的关系:
yarn install

可以看到,根目录下的 node_modules 中已经存在了 yarn-module1 和 yarn-module2 这两个包,与 lerna 的区别在于没有在各自的 package 下创建 node_modules,而是统一链接到根目录。

但,yarn-module2 中依赖的 yarn-module1,应该将其添加到 package.json 中,最好的方式是采用:

yarn workspace yarn-module2 add yarn-module1@^1.0.0
  1. 再来一次 script:
yarn workspace yarn-module2 run test

输出: 
yarn-module1
yarn-module2

文末

感谢大家阅读。

借鉴:
阿里巴巴业务中台前端专栏 - 图解 lerna publish