pnpm workspace 是 pnpm 提供的 Monorepo（单体仓库） 管理方案，允许在单个代码仓库中管理多个项目（包），并高效共享依赖。相比 npm/yarn workspace，pnpm 通过硬链接节省磁盘空间，依赖管理更高效。

一、核心概念

• Workspace（工作区）：一个包含多个子项目的根目录，通过 pnpm-workspace.yaml 定义。
• 共享依赖：所有子项目共用 node_modules，避免重复安装。
• 依赖提升：将共用的依赖提升到根目录的 node_modules，减少冗余。

二、初始化 Workspace

步骤 1：创建项目结构

mkdir my-monorepo && cd my-monorepo
pnpm init              # 初始化根目录 package.json

目录结构示例：

my-monorepo/
├── packages/
│   ├── app/           # 子项目1（如前端应用）
│   │   └── package.json
│   └── utils/         # 子项目2（如共享工具库）
│       └── package.json
├── pnpm-workspace.yaml
└── package.json

步骤 2：配置 pnpm-workspace.yaml

在根目录创建 pnpm-workspace.yaml，定义子项目路径：

packages:
  - "packages/*" # 匹配 packages/ 下的所有项目
  - "apps/*" # 也可以匹配其他目录

步骤 3：设置子项目

在每个子项目（如 packages/utils）中初始化 package.json：

cd packages/utils
pnpm init

确保 name 符合包命名规范（如 @my-monorepo/utils）。

---

3. 安装依赖

(1) 全局安装（根目录）

# 安装所有子项目的依赖（类似 `npm install`）
pnpm install

# 安装全局工具（如 typescript、eslint）
pnpm add -Dw typescript eslint

• -D：开发依赖（devDependencies）
• -w：安装在根目录（workspace root）

(2) 为子项目单独安装

# 进入子项目目录安装
cd packages/app
pnpm add react

# 或直接从根目录安装（指定子项目）
pnpm add react --filter @my-monorepo/app

• --filter：指定目标子项目（支持通配符，如 --filter "packages/*"）

(3) 子项目之间互相引用

# 在 packages/app 中引用 packages/utils
pnpm add @my-monorepo/utils --filter @my-monorepo/app

这会在 app/package.json 中添加：

{
  "dependencies": {
    "@my-monorepo/utils": "workspace:*"
  }
}

---

4. 运行脚本

(1) 运行单个子项目的脚本

# 进入子项目运行
cd packages/app
pnpm dev

# 或从根目录运行（推荐）
pnpm --filter @my-monorepo/app dev

(2) 并行运行所有子项目的脚本

pnpm -r run build     # 在所有子项目中运行 build 命令

• -r：递归执行（--recursive）

(3) 仅运行部分子项目的脚本

pnpm --filter "@my-monorepo/app" run dev
pnpm --filter "{packages/*,apps/*}" run test

---

5. 依赖管理优化

(1) 提升公共依赖

默认情况下，pnpm 会自动将公共依赖提升到根目录 node_modules，减少重复安装。

(2) 禁止依赖提升

在 pnpm-workspace.yaml 中设置：

shared-workspace-lockfile: false

(3) 查看依赖树

pnpm why lodash       # 查看 lodash 被哪些包依赖
pnpm list -r          # 递归列出所有子项目的依赖

---

6. 发布 Workspace 包

(1) 版本管理

使用 changesets 或 pnpm version 管理版本号：

# 更新所有子项目版本
pnpm version patch -r

(2) 发布到 npm

pnpm -r publish       # 递归发布所有包（需提前登录 npm）

---

7. 常见问题

Q1: 如何解决子项目之间的循环依赖？

• 使用 "peerDependencies" 替代直接依赖。
• 重构代码，提取公共逻辑到独立包。

Q2: 如何限制某些依赖只能在根目录安装？

在 pnpm-workspace.yaml 中设置：

neverBuiltDependencies:
  - fsevents # 禁止某些依赖安装

Q3: 如何兼容 npm/yarn workspace 项目迁移？

• 替换 workspace: 协议为具体版本号（如 "^1.0.0"）。
• 使用 pnpm import 从 yarn.lock 或 package-lock.json 生成 pnpm-lock.yaml。

---

总结

功能	命令示例
初始化 workspace	pnpm init + pnpm-workspace.yaml
安装依赖	pnpm add react --filter @my-monorepo/app
运行脚本	pnpm --filter @my-monorepo/app dev
批量操作	pnpm -r run build
发布包	pnpm -r publish

pnpm workspace 是 Monorepo 的最佳实践，适合管理复杂的前端/全栈项目（如 Next.js + NestJS + 共享库）。🚀

更新日志

2025/8/24 08:17

查看所有更新日志

• e7112-1于 2025/8/24