pnpm workspace Cheatsheet

为什么用它

一句话价值主张：如果你想在【多个项目/包】里用最少操作做到【统一依赖与脚本管理】，pnpm workspace 能在【10 分钟】内帮你完成。
三个立刻能感知的收益：
1. 一次安装，多包共享依赖，节省磁盘与时间。
2. 一条命令，批量跑 build/test/lint。
3. 本地包互相引用，不用发布也能联调。
适合：多前端/后端/工具包同仓库；需要共享配置与版本管理的团队。
不适合：只有单一项目且不需要分包管理。

3 步极速上手

目标：复制粘贴命令，看到第一个可见输出。

步骤 1：安装

npm i -g pnpm  # 全局安装 pnpm
pnpm -v        # 成功判定：输出版本号

步骤 2：创建最简示例

mkdir -p pnpm-ws-demo/packages/app && cd pnpm-ws-demo  # 创建 workspace 根目录
pnpm init -y                                            # 生成根 package.json
cat <<'YAML' > pnpm-workspace.yaml                       # 声明工作区范围
packages:
  - "packages/*"
YAML
cd packages/app
pnpm init -y                                            # 初始化子包
printf "console.log('hello pnpm workspace')\n" > index.js  # 可见输出
pnpm pkg set scripts.dev="node index.js"               # 添加启动脚本

步骤 3：验证成功

cd ../../
pnpm install                         # 在根目录安装所有依赖
pnpm -C packages/app run dev          # 成功判定：终端输出 hello pnpm workspace

每一步都写清：命令作用 + 成功判定。首次示例是“Hello World”级别。

高频命令

只保留日常开发最常用的 6–8 个命令，按频率排序。

安装与批量运行

pnpm install                 # 安装整个 workspace 依赖并生成 pnpm-lock.yaml
pnpm -r run build             # 递归执行所有包的 build 脚本
pnpm list -r --depth 0         # 列出所有 workspace 包（不展示依赖树）

按包过滤 / 定位

pnpm --filter app run dev      # 只运行名为 app 的包
pnpm --filter "./packages/*" run test  # 按路径批量过滤
pnpm -C packages/app run dev   # 在指定目录执行命令

依赖管理

pnpm add -w typescript         # 给 workspace 根添加依赖
pnpm add axios --filter app    # 只给 app 包添加依赖

实用但不高频的命令

维护与排查

pnpm up -r                     # 升级所有包依赖
pnpm why react                 # 查看依赖链，定位为什么会被安装
pnpm store prune               # 清理全局 store 缓存，释放磁盘
pnpm patch <pkg>               # 临时修改依赖并生成补丁

最小可用配置

# pnpm-workspace.yaml
packages:
  - "packages/*" # 工作区包路径

// package.json（workspace 根）
{
  "name": "pnpm-ws-demo",
  "private": true,
  "packageManager": "pnpm@latest"
}

常见问题

没有被识别为 workspace

症状：pnpm -r run build 只在根目录执行，或 pnpm list -r 只显示一个包

解决：

cat pnpm-workspace.yaml        # 确认文件在根目录且包含 packages/*
pnpm install                   # 在根目录重新安装

成功判定：pnpm list -r --depth 0 能看到多个包

本地包无法被引用

症状：Cannot find module 或 ERR_PNPM_NO_MATCHING_VERSION

解决：

pnpm -C packages/app pkg set "dependencies.@acme/utils=workspace:*"  # 添加 workspace 依赖
pnpm install                                                        # 重新链接

成功判定：在 app 中 import '@acme/utils' 不再报错

只在子包里安装依赖导致混乱

症状：依赖只出现在子包 node_modules，其他包找不到

解决：

cd ../..                         # 回到 workspace 根目录
pnpm install                     # 统一安装与链接

成功判定：根目录生成 pnpm-lock.yaml，各包依赖可互相解析

继续深入

官方文档：https://pnpm.io/workspaces
过滤与递归执行：https://pnpm.io/filtering
递归命令参考：https://pnpm.io/cli/recursive

微挑战

现在动手试试（≤ 3 分钟）：

按上面 3 步跑通基础示例
把 hello pnpm workspace 改成你自己的文本
重新执行 pnpm -C packages/app run dev 验证修改生效

记录遇到的问题和解决方案，建立实战经验。

pnpm workspace Cheatsheet

On this page