Monorepo 的这些坑，咱们帮你踩过了！

时间  2021-08-12
标签 css html node react webpack git github web shell npm 栏目 CSS 繁體版
原文   原文链接

前言

笔者目前所在团队是使用 Monorepo 的方式管理全部的业务项目，而随着项目的增多，稳定性以及开发体验受到挑战，诸多问题开始暴露，能够明显感觉到现有的 Monorepo 架构已经不足以支撑日渐庞大的业务项目。css

现有的 Monorepo 是基于 yarn workspace 实现，经过 link 仓库中的各个 package，达到跨项目复用的目的。package manager 也理所固然的选择了 yarn，虽然依赖了 Lerna，因为发包场景较为稀少，基本没有怎么使用。html

能够总结为如下三点：node

  • 经过 yarn workspace link 仓库中的 package
  • 使用 yarn 做为 package manager 管理项目中的依赖
  • 经过 lerna 在应用 app 构建前按照依赖关系构建其依赖的 packages

存在的问题

命令不统一

存在三种命令react

  1. yarn
  2. yarn workspace
  3. lerna

新人上手容易形成误解，部分命令之间功能存在重叠。webpack

发布速度慢

monorepo1

若是咱们须要发布 app1，则会git

  1. 全量安装依赖，app一、app二、app3 以及 package1 至 package6 的依赖都会被安装；
  2. package 所有被构建，而非仅有 app1 依赖的 package1 与 package2 被构建。

Phantom dependencies

一个库使用了不属于其 dependencies 里的 Package 称之为 Phantom dependencies（幻影依赖、幽灵依赖、隐式依赖），在现有 Monorepo 架构中该问题被放大（依赖提高）。github

monorepo-2

因为没法保证幻影依赖的版本正确性，给程序运行带来了不可控的风险。app 依赖了 lib-a，lib-a 依赖了 lib-x，因为依赖提高，咱们能够在 app 中直接引用 lib-x，这并不可靠，咱们可否引用到 lib-x，以及引用到什么版本的 lib-x 彻底取决于 lib-a 的开发者。web

NPM doppelgnger

相同版本的 Package 可能安装多份，打包多份。shell

假设存在如下依赖关系npm

monorepo-3

最终依赖安装可能存在两种结果：

  1. lib-x@^1 * 1 份，lib-x@^2 * 2 份
  2. lib-x@^2 * 1 份，lib-x@^1 * 2 份

最终本地会安装 3 份 lib-x，打包时也会存在三份实例，若是 lib-x 要求单例，则可能会形成问题。

Yarn duplicate

Yarn duplicate 及解决方案

假设存在如下依赖关系

monorepo-4

当 (p)npm 安装到相同模块时，判断已安装的模块版本是否符合新模块的版本范围，若是符合则跳过，不符合则在当前模块的 node_modules 下安装该模块。即 lib-a 会复用 app 依赖的 lib-b@1.1.0。

然而，使用 Yarn v1 做为包管理器，lib-a 会单独安装一份 lib-b@1.2.0。

peerDependencies 风险

Yarn 依赖提高，在 peerDependencies 场景下可能致使 BUG。

  1. app1 依赖 A@1.0.0
  2. app2 依赖 B@2.0.0
  3. B@2.0.0 将 A@2.0.0 做为 peerDependency，故 app2 也应该安装 A@2.0.0

若 app2 忘记安装 A@2.0.0，那么结构以下

--apps
    --app1
    --app2
--node_modules
    --A@1.0.0
    --B@2.0.0
复制代码

此时 B@2.0.0 会错误引用 A@1.0.0。

Package 引用规范缺失

目前项目内存在三种引用方式：

  1. 源码引用：使用包名引用。须要配置宿主项目的构建脚本，将该 Package 归入构建流程。相似于直接发布一个 TypeScript 源码包，引用该包的项目须要作必定的适配。
  2. 源码引用：使用文件路径引用。能够理解“宿主在自身 src 以外的源文件”，即宿主项目源代码的一部分，而非 Package。宿主须要提供该全部依赖，在 Yarn 依赖提高的前提下达到了跨项目复用，但存在较大风险。
  3. 产物引用。打包完成，直接经过包名引用产物。

Package 引用版本不肯定性

假设一个 Monorepo 中的 package1 发布至了 npm 仓库，那么 Monorepo 中的 app1 应当如何在 package.json 中编写引用 package1 的版本号？

package1/packag.json

{
  "name": "package1",
  "version": "1.0.0"
}
复制代码

app1/package.json

{
  "name": "app1",
  "dependencies": {
    "package-1": "?" // 这里的版本号应该怎么写？`*` or `1.0.0`
  }
}
复制代码

在处理 Monorepo 中项目的互相引用时，Yarn 会进行如下几步判断：

  1. 判断当前 Monorepo 中，是否存在匹配 app1 所需版本的 package1；
  2. 若存在，执行 link 操做，app1 直接使用本地 package1；
  3. 若不存在，从远端 npm 仓库拉取符合版本的 package1 供 app1 使用。

须要特别注意的是：* 没法匹配 prerelease 版本 👉 Workspace package with prerelease version and wildcard dep version #6719。

假设存在如下场景：

  1. package1 此前已经发布了 1.0.0 版本，此时远端仓库与本地 Monorepo 中代码一致；
  2. 产品同窗提了一个只服务于 Monorepo 内部应用的需求；
  3. package1 在 1.0.0 版本下迭代，无需变动版本号发布；
  4. Yarn 判断 Monorepo 中的 package1 版本知足了 app1 所需版本（* 或 1.0.0）；
  5. app1 顺利使用上 package1 的最新特性。

直到某天，该需求特性须要提供给外部业务方使用。

  1. pacakge1 将版本改成 1.0.0-beta.0 并进行发版；
  2. Yarn 判断当前 Monorepo 中的 package1 版本不知足 app1 所需版本；
  3. 从远端拉取 package1@1.0.0 供 app1 使用；
  4. 远端 package@1.0.0 已经落后 app1 先前使用的本地 package@1.0.0 太多；
  5. 准备事故通报以及复盘。

这种不肯定性，致使引用此类 package 时会常常犯嘀咕：我到底引用的是本地版本仍是远端版本？为何有时候是本地版本，有时候是远端版本？我想用上 package1 的最新内容还须要时刻保持与 package1 的版本号保持一致 ，那我干吗用 Monorepo ？

yarn.lock 冲突

(p)npm 支持自动化解决 lockfile 冲突，yarn 须要手动处理，在大型 Monorepo 场景下，几乎每次分支合并都会遇到 yarn.lock 冲突。

  • 不解决冲突无脑 yarn，yarn.lock 会直接失效，所有版本更新到 package.json 最新，风险太大，失去 lockfile 的意义；
  • 人工解决冲突每每会出现 Git conflict with binary files，只能使用 master 的提交再从新 yarn，流程繁琐。

Automatically resolve conflicts in lockfile · Issue #2036 · pnpm/pnpm

能够发现，现有 Monorepo 管理方式缺陷过多，随着其内项目的不断增长，构建速度会愈来愈慢，同时程序的健壮性没法获得保证。仅凭开发人员自觉是不可靠的，咱们须要一套解决方案。

推荐阅读：node_modules 困境

解决方案

pnpm

Fast, disk space efficient package packageManager

在 npm@3 以前， node_modules 的结构是干净且可预测的，由于 node_modules 中的每一个依赖项都有其本身的 node_modules 文件夹，其全部依赖项都在 package.json 中指定。

node_modules
└─ foo
   ├─ index.js
   ├─ package.json
   └─ node_modules
      └─ bar
         ├─ index.js
         └─ package.json
复制代码

可是这样带来了两个很严重的问题：

  1. 依赖层级过深在 Windows 下会出现问题；
  2. 同一 Package 做为其余多个不一样 Package 的依赖项时，会被拷贝不少次。

为了解决这两个问题，npm@3 从新思考了 node_modules 的结构，引入了平铺的方案。因而就出现了下面咱们所熟悉的结构。

node_modules
├─ foo
|  ├─ index.js
|  └─ package.json
└─ bar
   ├─ index.js
   └─ package.json
复制代码

与 npm@3 不一样，pnpm 使用另一种方式解决了 npm@2 所遇到的问题，而非平铺 node_modules。

在由 pnpm 建立的 node_modules 文件夹中，全部 Package 都与自身的依赖项分组在一块儿（隔离），可是依赖层级却不会过深（软连接到外面真正的地址）。

-> - a symlink (or junction on Windows)

node_modules
├─ foo -> .registry.npmjs.org/foo/1.0.0/node_modules/foo
└─ .registry.npmjs.org
   ├─ foo/1.0.0/node_modules
   |  ├─ bar -> ../../bar/2.0.0/node_modules/bar
   |  └─ foo
   |     ├─ index.js
   |     └─ package.json
   └─ bar/2.0.0/node_modules
      └─ bar
         ├─ index.js
         └─ package.json
复制代码
  1. 基于非扁平化的 node_modules 目录结构，解决 Phantom dependencies。Package 只可触达自身依赖。
  2. 经过软链复用相同版本的 Package，避免重复打包（相同版本），解决 NPM doppelgnger（顺带解决磁盘占用）。

能够发现，不少与包管理器相关的问题就此迎刃而解。

Rush

a scalable monorepo manager for the web

  1. 命令统一。

rush(x) xxx 一把梭，减小新人上手成本。同时 Rush 除了 rush add 以及 rushx xxx 等命令须要在指定项目下运行，其余命令均为全局命令，可在项目内任意目录执行，避免了在终端频繁切换项目路径的问题。

monorepo-5

  1. 强大的依赖分析能力。

Rush 中的许多命令支持分析依赖关系，好比 -t(to) 参数：

$ rush install -t @monorepo/app1
复制代码

该命令只会安装 app1 的依赖及其 app1 依赖的 package 的依赖，即按需安装依赖。

$ rush build -t @monorepo/app1
复制代码

该命令会执行 app1 以及 app1 依赖的 package 的构建脚本。

相似的，还有 -f(from) 参数，可使命令只做用于当前 package 以及依赖了该 package 的 package。

  1. 保证依赖版本一致性

Monorepo 中的项目应当尽可能保证依赖版本的一致性，不然颇有可能出现重复打包以及其余的问题。

Rush 则提供了许多能力来保证这一点，如rush check、rush add -p package-name -m 以及 ensureConsistentVersions。

有兴趣的同窗能够自行翻阅 Rush 的官方文档，十分详尽，对于一些常见问题也有说明。

Package 引用规范

monorepo-12

产物引用

传统引用方式，构建完成后，app 直接引用 package 的构建产物。开发阶段能够经过构建工具提供的能力保证明时构建（如 tsc --watch）

  • 优势：规范，对 app 友好。
  • 缺点：随着模块增多，package 热更新速度可能变得难以忍受。

源码引用

package.json 中的 main 字段配置为源文件的入口文件，引用该 package 的 app 须要将该 package 归入编译流程。

  • 优势：借助 app 的热更新能力，自身没有生成构建产物的过程，热更新速度快
  • 缺点：须要 app 进行适配， alias 适配繁琐；

引用规范

  1. 对于项目内部使用的 packages ，称为 features，不该当向外发布，直接将 main 字段设置为源文件入口并配置 app 项目的 webpack，走后编译形式。
  2. 对于须要对外发布的 packages，不该该也不容许引用 features，必需要有构建过程，若是须要使用源码开发增长热更新速度，能够新增一个自定义的入口字段，app 的 webpack 配置中优先识别该入口字段便可。

补充：rush build 命令是支持构建产物缓存的，若是 app 拆分粒度够小，可复用的包足够多，同时打包镜像支持构建产物缓存的 set 与 get，就能够作到增量构建 app。

Workspace protocol (workspace:)

在 PNPM 和 Yarn 支持 Workspace 能力以前，Rush 就诞生了。 Rush 的方法是将全部软件包集中安装在 common / temp 文件夹中，而后 Rush 建立从每一个项目到 common / temp 的符号连接。与 PNPM Workspace 本质上是等效的。

开启 PNPM workspace 能力从而可使用 workspace:协议保证引用版本的肯定性，使用了该协议引用的 package 只会使用 Monorepo 中的内容。

{
  "dependencies": {
    "foo": "workspace:*",
    "bar": "workspace:~",
    "qar": "workspace:^",
    "zoo": "workspace:^1.5.0"
  }
}
复制代码

推荐引用 Monorepo 内的 package 时统一使用该协议，引用本地最新版本内容，保证更改可以及时扩散同步至其余项目，这也是 Monorepo 的优点所在。

若必定要使用远端版本，须要在 rush.json 中配置具体 project （增长 cyclicDependencyProjects 配置），详见 rush_json。

很幸运的是 PNPM workspace 中 workspace:* 能够匹配 prerelease 版本 👉 Local prerelease version of packages should be linked only if the range is *

问题记录

Monorepo Project Dependencies Duplicate

这个问题相似于前面提到的 Yarn duplicate，但并非 Yarn 独有的。

假设存在如下依赖关系（将 Yarn duplicate 的例子进行改造，放在 Monorepo 场景中）

app1 以及 package1 同属于 Monorepo 内部 project。

monorepo-8

在 Rush(pnpm)/Yarn 项目中，会严格按照 Monorepo 内 project 的 package.json 所声明的版本进行安装，即 app1 安装 lib-a@1.1.0，package1 安装 lib-a@1.2.0。

此时对 app1 进行打包，则 lib-a@1.1.0 和 lib-a@1.2.0 都会被打包。

对这个结果你也许会有一些意外，但仔细想一想，又很天然。

换一种方式理解，整个 Monorepo 是一个大的虚拟 project，咱们全部的 project 都做为这个虚拟 project 的直接依赖存在。

{
  "name": "fake-project",
  "version": "1.0.0",
  "dependencies": {
    "@fake-project/app1": "1.0.0",
    "@fake-project/package1": "1.0.0"
  }
}
复制代码

安装依赖时，(p)npm 首先下载直接依赖项，而后再下载间接依赖项，而且在安装到相同模块时，判断已安装的模块版本（直接依赖项）是否符合新模块（间接依赖项）的版本范围，若是符合则跳过，不符合则在当前模块的 node_modules 下安装该模块。

而 app1 和 package1 的直接依赖关系 lib-a 是该 fake-project 的间接依赖项，没法知足上述判断条件，因而按照对应 package.json 中描述的版本安装。

解决方案：Rush: Preferred versions

Rush 能够经过手动指定 preferredVersions 的方式，避免两个可兼容版本的重复。这里将 Monorepo 中 lib-a 的 preferredVersions 指定为 1.2.0，至关于在该虚拟 project 下直接安装了指定的版本的模块，做为直接依赖项。

{
  "name": "fake-project",
  "version": "1.0.0",
  "dependencies": {
    "@fake-project/app1": "1.0.0",
    "@fake-project/package1": "1.0.0",
    "lib-a": "1.1.0"
  }
}
复制代码

对于 Yarn，因为 Yarn duplicate 的存在，就算在根目录指定安装肯定版本的 lib-a 也是无效的。 可是依旧有两种方案能够进行处理：

  1. 经过 yarn-deduplicate 针对性的修改 yarn.lock；
  2. 使用resolutions 字段。过于粗暴，不像 preferredVersions 能够容许不兼容版本的存在，不推荐。

须要谨记：在 Yarn 下消除重复依赖，也应该一个 Package 一个 Package 的去进行处理，当心使得万年船。

  1. 对于存在反作用的公共库，版本最好保持统一；
  2. 对于其余的体积小（或支持按需加载）、无反作用的公共库，重复打包在必定程度上能够接受的。

prettier

因为根目录再也不存在 node_modules，故须要每一个项目安装一个 prettier 做为 devDependency 并编写 .prettierrc.js 文件。

本着偷懒的原则，根目录新建 .prettierrc.js（不依赖任何第三方包），全局安装 prettier 解决该问题。

eslint

先看一个场景，若在项目中使用 eslint-config-react-app，除了须要安装 eslint-config-react-app，还须要安装一系列 peerDependencies 插件。

monorepo-10

monorepo-11

为何 eslint-config-react-app 不将这一系列插件做为 dependencies 内置，而是做为 peerDependencies？使用者并不须要关心预设配置内引用了哪些插件。

具体讨论能够查看该 issue，里面有相关问题的讨论： Support having plugins as dependencies in shareable config #3458 。

总而言之：和 eslint 插件的具体查找方式有关，若是由于依赖提高失败（多版本冲突），致使须要的插件被装在了非根目录 node_modules 下，就可能产生问题，而用户自行安装 peerDependencies 能够保证不会出现该问题。

固然，咱们也发现一些开源的 eslint 预设配置不须要安装 peerDependencies，这些预设利用了 yarn 和 npm 的扁平 node_modules 结构，也就是依赖提高，装的包都被提高至根目录 node_modules，故能够正常运做。即使如此，在基于 Yarn 的 Monorepo 中，依赖一旦复杂起来，就可能出现插件没法被查找到的状况，可以正常运转就像一个有趣的巧合。

在 Rush 中，不存在依赖提高（提高也不必定靠谱），装一系列的插件又过于繁琐，则能够经过打补丁的方式绕过。

git hooks

一般会在项目中使用 husky 注册 pre-commit 和 commit-msg 钩子，用于校验代码风格以及 commit 信息。

很明显，在 Rush 项目的结构下，根目录是没有 node_modules 的，没法直接使用 husky。

咱们能够借助 rush init-autoinstaller 的能力来达到同样的效果，本节主要参考官方文档 Installing Git hooks 以及 Enabling Prettier 的内容。

# 初始化一个名为 rush-lint 的 autoinstaller

$ rush init-autoinstaller --name rush-lint

$ cd common/autoinstallers/rush-lint

# 安装 lint 所需依赖

$ pnpm i @commitlint/cli @commitlint/config-conventional @microsoft/rush-lib eslint execa prettier lint-staged

# 更新 rush-lint 的 pnpm-lock.yaml

$ rush update-autoinstaller --name rush-lint
复制代码

在 rush-lint 目录下新增 commit-lint.js 以及 commitlint.config.js，内容以下

commit-lint.js

const path = require('path');
const fs = require('fs');
const execa = require('execa');

const gitPath = path.resolve(__dirname, '../../../.git');
const configPath = path.resolve(__dirname, './commitlint.config.js');
const commitlintBinPath = path.resolve(__dirname, './node_modules/.bin/commitlint');

if (!fs.existsSync(gitPath)) {
    console.error('no valid .git path');
    process.exit(1);
}

main();

async function main() {
    try {
        await execa('bash', [commitlintBinPath, '--config', configPath, '--cwd', path.dirname(gitPath), '--edit'], {
            stdio: 'inherit',
        });
    } catch (\_e) {
        process.exit(1);
    }
}
复制代码

commitlint.config.js

const rushLib = require("@microsoft/rush-lib");

const rushConfiguration = rushLib.RushConfiguration.loadFromDefaultLocation();

const packageNames = [];
const packageDirNames = [];

rushConfiguration.projects.forEach((project) => {
  packageNames.push(project.packageName);
  const temp = project.projectFolder.split("/");
  const dirName = temp[temp.length - 1];
  packageDirNames.push(dirName);
});
// 保证 scope 只能为 all/package name/package dir name
const allScope = ["all", ...packageDirNames, ...packageNames];

module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "scope-enum": [2, "always", allScope],
  },
};
复制代码

注意：此处不须要新增 prettierrc.js（根目录已存在） 以及 eslintrc.js（各项目已存在）。

根目录新增 .lintstagedrc 文件

.lintstagedrc

{
  "{apps,packages,features}/**/*.{js,jsx,ts,tsx}": [
    "eslint --fix --color",
    "prettier --write"
  ],
  "{apps,packages,features}/**/*.{css,less,md}": ["prettier --write"]
}
复制代码

完成了相关依赖的安装以及配置的编写，咱们接下来将相关命令执行注册在 rush 中。

修改 common/config/rush/command-line.json 文件中的 commands 字段。

{
  "commands": [
    {
      "name": "commitlint",
      "commandKind": "global",
      "summary": "Used by the commit-msg Git hook. This command invokes commitlint to lint commit message.",
      "autoinstallerName": "rush-lint",
      "shellCommand": "node common/autoinstallers/rush-lint/commit-lint.js"
    },
    {
      "name": "lint",
      "commandKind": "global",
      "summary": "Used by the pre-commit Git hook. This command invokes eslint to lint staged changes.",
      "autoinstallerName": "rush-lint",
      "shellCommand": "lint-staged"
    }
  ]
}
复制代码

最后，将 rush commitlint 以及 rush lint 两个命令分别与 commit-msg 以及 pre-commit钩子进行绑定。 common/git-hooks 目录下增长 commit-msg 以及 pre-commit 脚本。

commit-msg

#!/bin/sh

node common/scripts/install-run-rush.js commitlint || exit $? #++
复制代码

pre-commit

#!/bin/sh

node common/scripts/install-run-rush.js lint || exit $? #++
复制代码

如此，便完成了需求。

避免全局安装 eslint 以及 prettier

通过上一节的处理，在 rush-lint 目录下安装了 eslint 以及 prettier 后，咱们便无需全局安装了，只须要配置一下 VSCode 便可。

{
  // ...
  "npm.packageManager": "pnpm",
  "eslint.packageManager": "pnpm",
  "eslint.nodePath": "common/autoinstallers/rush-lint/node_modules/eslint",
  "prettier.prettierPath": "common/autoinstallers/rush-lint/node_modules/prettier"
  // ...
}
复制代码

附录

经常使用命令

yarn rush(x) detail
yarn install rush install 安装依赖
yarn upgrade rush update rush update 安装依赖，基于 lock 文件
rush update --full 全量更新到符合 package.json 的最新版本
yarn add package-name rush add -p package-name yarn add 默认安装版本号为 ^ 开头，可接受小版本更新
rush add 默认安装版本号为 ~ 开头，仅接受补丁更新
rush add 可经过增长 --caret 参数达到与 yarn add 效果一致
rush add 不可一次性安装多个 package
yarn add package-name --dev rush add -p package-name --dev -
yarn remove package-name - rush 不提供 remove 命令
- rush build 执行文件存在变动（基于 git）的项目的 build 脚本
rush build -t @monorepo/app1 表示只构建 @monorepo/app1 及其依赖的 package
rush build -T @monorepo/app1 表示只构建 @monorepo/app1 依赖的 package，不包含其自己
- rush rebuild 默认执行全部项目的 build 脚本
yarn xxx(自定义脚本) rushx xxx(自定义脚本) yarn xxx 执行当前目录下 package.json 中的 xxx 脚本(npm scripts)
rushx xxx 同理。能够直接执行 rushx 查看当前项目所支持的脚本命令。

工做流

# 从 git 拉取最新变动
$ git pull

# 更新 NPM 依赖
$ rush update

# 从新打包 @monorepo/app1 依赖的项目（不含包其自己）
$ rush rebuild -T @monorepo/app1

# 进入指定项目目录
$ cd ./apps/app1

# 启动项目 ​
$ rushx start # or rushx dev
复制代码

参考文章

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程