pnpm-workspace.yaml 是 pnpm 的“项目组织与调度中枢”，告诉 pnpm：哪些目录是同一个 workspace，以及这些包之间如何协同工作。

定义哪些包属于同一个仓库

packages:
  - packages/*
  - apps/*

• packages/* 下面每个有 package.json 的目录，都是一个包
• apps/* 下面每个 app 也是一个包

Workspace 内包本地互相引用

packages/
  utils/
  ui/
apps/
  admin/

在 apps/admin/package.json 里：

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

效果是：

• 不去 npm 下载
• 直接 软链接到本地 packages/utils
• 改代码立刻生效

这是 monorepo 的灵魂能力。

依赖统一安装、统一锁定

在根目录执行pnpm install
pnpm 会：

• 扫描 pnpm-workspace.yaml 里的所有包
• 统一生成 一份 pnpm-lock.yaml
• 所有包共享同一个依赖树

支持 catalog

pnpm-workspace.yaml 里可以这样写：

catalog:
  vite: ^5.1.0
  vue: ^3.4.0
  typescript: ^5.3.3

子包中：

"devDependencies": {
  "vite": "catalog:",
  "vue": "catalog:"
}

版本集中管理，企业级工程标配.

支持 workspace 协议（workspace:*）

"@my/ui": "workspace:*"     // 任意版本
"@my/ui": "workspace:^"     // 遵循 semver
"@my/ui": "workspace:~"

批量执行命令

pnpm -r build
pnpm -r test
pnpm -r lint

• -r = recursive
• 对 workspace 里的 所有包 执行

corepack 可以把它理解成 Node.js 自带的“包管理器管理器” 。
corepack 用来管理和锁定项目使用的包管理器（比如 pnpm / yarn），而不是管理依赖本身。

为什么会有 corepack

以前的情况很乱：

• 有的人用 npm
• 有的人用 yarn
• 有的人用 pnpm
• 同一个项目里，不同人用的 包管理器版本还不一样

结果就是：

“我这能跑，你那为啥装不起来？”

corepack 的出现，就是为了解决 “到底用哪个包管理器、用哪个版本” 这个问题。

corepack 能干什么

1️⃣ 统一项目使用的包管理器

在 package.json 里可以写：

{
  "packageManager": "pnpm@8.15.4"
}

含义是：

这个项目 必须 用 pnpm，而且版本是 8.15.4

这时候：

• 你 pnpm install
• 同事 npm install
• CI 里跑 pnpm install

👉 corepack 会自动帮你下载并使用正确版本的 pnpm

不用大家手动装。

---

2️⃣ 自动安装 & 切换 yarn / pnpm

你甚至不需要提前全局装 pnpm：

corepack enable
pnpm install

如果项目声明的是：

"packageManager": "yarn@3.6.1"

corepack 会：

• 自动下载 yarn 3.6.1
• 用它来执行命令

你本地有没有 yarn 👉 不重要

---

3️⃣ 防止“包管理器版本不一致”的坑

比如：

• A 用 pnpm 7
• B 用 pnpm 8
• lock 文件结构都不一样

corepack 可以 强制版本一致，从源头避免：

• lockfile 被反复改
• CI 跑不过
• “我这没问题啊”的玄学 bug

---

corepack 和 npm / yarn / pnpm 的关系

可以这么理解👇

corepack
  ├── 管理 pnpm
  ├── 管理 yarn
  └── 管理 npm（间接）

• npm / yarn / pnpm：真正干活的
• corepack：负责“发工具、管版本、做协调”

---

常用命令速览 🧠

# 启用 corepack（Node 16+ 自带）
corepack enable

# 查看当前 corepack 版本
corepack --version

# 指定并激活某个包管理器版本
corepack prepare pnpm@8.15.4 --activate

---

什么时候一定要用 corepack

非常推荐用在这些场景👇

• 团队协作项目
• monorepo（pnpm / yarn workspace）
• CI / Docker / 线上构建
• 你已经被 “lockfile 一直变” 折磨过 😅

---

一句话总结

corepack 不是用来装依赖的，是用来“管包管理器的版本和使用权”的。
它让“这个项目该用哪个包管理器、哪个版本”变成一件确定的事。