第六章：大型项目管理术——Monorepo 架构与 PNPM Workspaces 实战

6.1. 什么是 Monorepo？它与传统的 Multi-repo 有何不同？

在软件开发中，代码仓库的管理方式主要有两种：

• Multi-repo (多仓库): 这是最传统、最常见的方式。每个项目、每个库都有自己独立的 Git 仓库。例如，webapp 在一个仓库，ui-components 在另一个仓库。
• Monorepo (单体仓库): 将所有相关的项目、库都放在同一个 Git 仓库中进行管理。例如，webapp 和 ui-components 都在同一个仓库的不同子目录中。

这两种模式在工作流、代码共享、版本控制等方面有着天壤之别。

6.2. Monorepo 的优势：以“设计系统”为例

为了更具体地感受 Monorepo 的威力，让我们构思一个真实的企业级场景：Acme 公司要构建自己的设计系统。

这个系统至少包含三个包：

• @acme/ui-components: 核心的 UI 组件库 (React/Vue)。
• @acme/docs: 用于展示和测试组件的文档站 (VitePress/Storybook)。
• @acme/webapp: 使用这套组件库的官方主应用。

在 Multi-repo 模式下，工作流会是这样：

1. 修改了 @acme/ui-components 里的一个按钮组件。
2. 为了在文档站里看效果，需要先将组件库发布一个 beta 版本到 npm。
3. @acme/docs 项目更新依赖，安装这个 beta 版本，然后启动调试。
4. 调试通过后，再将组件库发布一个正式版。
5. @acme/webapp 和 @acme/docs 再更新到正式版。这个流程因为涉及多次发布和安装，效率极其低下。

而在 Monorepo 模式下，工作流将变得无比丝滑：

1. 直接在 Monorepo 中修改 @acme/ui-components 的按钮组件代码。
2. 由于 @acme/docs 是直接通过源码引用组件库的，它的开发服务器会 立即热更新，实时看到修改效果。
3. 调试完成后，进行 一次原子化提交，这个提交同时包含了组件库的修改和（可能有的）文档站的适配修改。

6.3. 实战入门：使用 PNPM Workspaces 搭建你的第一个 Monorepo

PNPM 内置了对 Monorepo（在 PNPM 中称为 Workspaces/工作区）的顶级支持。现在，让我们亲手搭建上面提到的 Acme 设计系统。

第一步：创建 Monorepo 根目录

1
2
3
4
5
6
7
8
9

# 创建并进入项目根目录
mkdir acme-design-system && cd acme-design-system

# 初始化根 package.json
pnpm init

在 package.json 的 下方加上 private: true 是 Monorepo 根目录的最佳实践，它表示这个包是私有的，不会被发布到公共仓库 。
  "packageManager": "pnpm@10.14.0",
  "private": true

第二步：定义工作区 (Workspace)

创建 pnpm-workspace.yaml 文件，这是声明此项目为 Monorepo 的“开关”。

文件路径: acme-design-system/pnpm-workspace.yaml

1
2
3

packages:
  # 我们约定，所有子项目都放在 'packages' 目录下
  - 'packages/*'

第三步：创建子项目

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 创建用于存放所有子项目的目录
mkdir packages

# 进入 packages 目录并创建三个子项目
cd packages
mkdir ui-components
mkdir docs
mkdir webapp
# 分别初始化每个子项目
cd ui-components && pnpm init && cd ..
cd docs && pnpm init && cd ..
cd webapp && pnpm init && cd ..

# 回到项目根目录
cd ..

此时，你的项目结构应该是这样：

1
2
3
4
5
6
7
8
9
10

# acme-design-system/
├── packages/
│   ├── docs/
│   │   └── package.json
│   ├── ui-components/
│   │   └── package.json
│   └── webapp/
│       └── package.json
├── package.json
└── pnpm-workspace.yaml

第四步：安装公共依赖

我们的三个子项目很可能都依赖 react 和 typescript。我们可以把这些公共依赖安装在 Monorepo 的 根目录，让所有子项目共享。

使用 -w 或 --workspace-root 标志来告诉 PNPM 在根目录安装。

1
2

# 在 Monorepo 根目录执行
pnpm add react react-dom typescript -D -w

执行后，react 等依赖会被安装到根目录的 node_modules 中，并被自动“提升”（hoist），所有子项目都可以直接引用到它们，无需重复安装。

6.4. 依赖管理与内部包的互相引用

这是 Monorepo 最神奇的地方：如何让 @acme/webapp 依赖本地的 @acme/ui-components？

第一步：修改子项目名称

为了能互相引用，我们需要先给子项目 package.json 里的 name 字段赋予规范的、带作用域的名称。

• packages/ui-components/package.json -> "name": "@acme/ui-components"
• packages/docs/package.json -> "name": "@acme/docs"
• packages/webapp/package.json -> "name": "@acme/webapp"

第二步：使用 workspace:* 协议

现在，我们编辑 webapp 的 package.json，让它依赖 ui-components：

文件路径: packages/webapp/package.json

1
2
3
4
5
6
7
8

{
  "name": "@acme/webapp",
  "version": "1.0.0",
  ...
  "dependencies": {
    "@acme/ui-components": "workspace:*"
  }
}

workspace:* 这个特殊的协议告诉 PNPM：“我依赖的 @acme/ui-components 不是 NPM 仓库里的某个版本，而是 当前工作区中的那个本地包”。

第三步：运行 pnpm install

在 Monorepo 根目录 运行：

1

pnpm install

PNPM 会识别到 workspace:* 协议，然后它不会去下载任何东西，而是会在 packages/webapp/node_modules 目录下，创建一个指向 packages/ui-components 目录的 符号链接。

第四步：在子项目中运行脚本

如果你想运行 webapp 的 dev 脚本，可以使用 -F 或 --filter 标志：

1
2

# 假设 webapp 的 package.json 中有 "dev": "vite"
pnpm --filter @acme/webapp dev

这个命令会精准地只运行指定子项目的脚本，是 Monorepo 开发中的日常操作。

6.5. 本章核心速查总结

6.6. 高频面试题与陷阱