pnpm-workspace

pnpm 工作区

概述

pnpm 工作区通过 pnpm-workspace.yaml、用于链接本地包的 workspace: 协议，以及强大的筛选功能，内置支持 monorepo，可在指定包中运行命令。目录（Catalog）可确保所有工作区包使用一致的依赖版本。

适用场景： 多包仓库、由应用使用的共享库、在多个包之间统一管理依赖，以及在部分包中运行命令。

不适用场景： 单包项目、已使用 npm/yarn 工作区的项目（需要迁移）、需要为各个包使用浮动依赖版本的项目。

快速参考

模式	API / 配置	要点
定义工作区	在 pnpm-workspace.yaml 中配置 packages glob	glob 会匹配包含 package.json 的目录
链接本地包	"dep": "workspace:*"	始终解析为本地工作区包
按版本范围链接	"dep": "workspace:^1.0.0"	如果本地版本不满足范围，安装将失败
默认目录	pnpm-workspace.yaml 中的 catalog: 键	依赖版本的唯一真实来源
命名目录	使用命名分组的 catalogs: 键	多个版本集（例如 react18、react17）
在包中使用目录	"dep": "catalog:" 或 "dep": "catalog:name"	在 pnpm publish 时解析为实际版本
按名称筛选	--filter <name> 或 -F <name>	精确名称或 glob 模式（@scope/*）
同时筛选依赖	--filter "foo..."	包及其所有依赖
同时筛选依赖方	--filter "...foo"	包及所有依赖它的包
按目录筛选	--filter "./packages/app"	指定目录路径下的所有包
按 Git 变更筛选	--filter "[origin/main]"	自某次提交或分支以来有变更的包
从筛选结果中排除	--filter "!foo"	从选取结果中移除匹配的包
在包中运行脚本	pnpm --filter <pkg> <script>	仅在匹配的包中运行脚本
递归运行	pnpm -r run <script>	在所有工作区包中运行脚本
安装全部依赖	pnpm install	整个工作区使用单个锁文件
发布工作区包	pnpm publish	将 workspace: 和 catalog: 替换为实际版本
注入工作区依赖	在 .npmrc 中设置 inject-workspace-packages=true	使用硬链接而非符号链接；部署时必需
脚本安全（v10+）	package.json 中的 allowBuilds	默认阻止生命周期脚本；可按依赖选择启用

常见错误

错误	正确做法
使用 workspace:* 后直接发布	pnpm 会在发布时自动将 workspace:* 替换为实际版本
忘记在 packages: 中列出目录	每个软件包目录都必须匹配 pnpm-workspace.yaml 中的一个 glob
在工作区软件包中使用 npm install	始终从工作区根目录运行 pnpm install
在多个软件包中硬编码重复的版本	使用 catalog: 集中定义版本
在子软件包中运行 pnpm install	从工作区根目录运行；使用 --filter 指定目标软件包
以为 --filter 会匹配目录名称	--filter 匹配 package.json 的 name 字段，而不是目录名称
在 zsh 中未转义排除筛选器里的 !	使用 \! 或为筛选器加引号：--filter="!foo"
对非工作区依赖使用 workspace:	workspace: 协议仅适用于工作区中定义的软件包
升级到 pnpm 10 后生命周期脚本失败	pnpm 10 默认会阻止脚本；在配置中的 allowBuilds 里添加依赖
使用 pnpm deploy 时未启用 inject-workspace-packages	在 .npmrc 中设置 inject-workspace-packages=true（pnpm 10 必需）

委派

• 工作区脚手架：使用 Explore Agent 探索现有软件包结构
• 依赖审计：使用 Task Agent 检查各软件包之间的版本一致性

如果有 turborepo 技能，请将构建编排、任务缓存和 CI 优化委派给它。 如果有 changesets 技能，请将版本管理、变更日志生成和 npm 发布委派给它。

参考资料

• 工作区设置、工作区协议和目录
• 筛选软件包以执行指定命令
• 工作区软件包间共享配置
• Monorepo 集成：pnpm + Turborepo + Changesets 流水线