pnpm-workspace

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pnpm Workspace

Overview

概述

pnpm workspaces provide built-in monorepo support through

pnpm-workspace.yaml

, the

workspace:

protocol for local package linking, and powerful filtering to run commands across specific packages. Catalogs enforce consistent dependency versions across all workspace packages.

When to use: Multi-package repositories, shared libraries with consuming apps, consistent dependency management across packages, running commands on subsets of packages.

When NOT to use: Single-package projects, projects already using npm/yarn workspaces (migration required), projects that need floating dependency versions per package.

pnpm workspaces通过

pnpm-workspace.yaml

、用于本地包链接的

workspace:

协议，以及强大的过滤功能为monorepo提供内置支持，可跨特定包运行命令。Catalogs可确保所有工作区包的依赖版本保持一致。

适用场景： 多包仓库、包含消费应用的共享库、跨包的一致依赖管理、在部分包子集上运行命令。

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

Quick Reference

快速参考

Pattern	API / Config	Key Points
Define workspace	`pnpm-workspace.yaml` with `packages` globs	Globs match directories containing `package.json`
Link local package	`"dep": "workspace:*"`	Always resolves to local workspace package
Link with version range	`"dep": "workspace:^1.0.0"`	Fails install if local version does not satisfy range
Default catalog	`catalog:` key in `pnpm-workspace.yaml`	Single source of truth for dependency versions
Named catalog	`catalogs:` key with named groups	Multiple version sets (e.g., `react18` , `react17` )
Use catalog in package	`"dep": "catalog:"` or `"dep": "catalog:name"`	Resolved to actual version on `pnpm publish`
Filter by name	`--filter <name>` or `-F <name>`	Exact name or glob pattern ( `@scope/*` )
Filter with dependencies	`--filter "foo..."`	Package and all its dependencies
Filter with dependents	`--filter "...foo"`	Package and all packages that depend on it
Filter by directory	`--filter "./packages/app"`	All packages under a directory path
Filter by git changes	`--filter "[origin/main]"`	Packages changed since a commit or branch
Exclude from filter	`--filter "!foo"`	Remove matching packages from selection
Run script in package	`pnpm --filter <pkg> <script>`	Runs script only in matched packages
Recursive run	`pnpm -r run <script>`	Runs script in all workspace packages
Install all	`pnpm install`	Single lockfile for entire workspace
Publish workspace pkg	`pnpm publish`	Replaces `workspace:` and `catalog:` with real versions
Inject workspace deps	`inject-workspace-packages=true` in `.npmrc`	Hard-links instead of symlinks; required for deploy
Script security (v10+)	`allowBuilds` in `package.json`	Lifecycle scripts blocked by default; opt-in per dep

模式	API/配置	关键点
定义工作区	带有 `packages` 通配符的 `pnpm-workspace.yaml`	通配符匹配包含 `package.json` 的目录
链接本地包	`"dep": "workspace:*"`	始终解析为本地工作区包
带版本范围的链接	`"dep": "workspace:^1.0.0"`	若本地版本不满足范围，安装会失败
默认Catalog	`pnpm-workspace.yaml` 中的 `catalog:` 键	依赖版本的单一可信来源
命名Catalog	带有命名分组的 `catalogs:` 键	多版本集合（例如 `react18` 、 `react17` ）
在包中使用Catalog	`"dep": "catalog:"` 或 `"dep": "catalog:name"`	在 `pnpm publish` 时会解析为实际版本
按名称过滤	`--filter <name>` 或 `-F <name>`	精确名称或通配符模式（ `@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`	默认阻止生命周期脚本；需为每个依赖手动开启

Common Mistakes

常见错误

Mistake	Correct Pattern
Using `workspace:*` then publishing as-is	pnpm automatically replaces `workspace:*` with real versions on publish
Forgetting to list directory in `packages:`	Every package directory must match a glob in `pnpm-workspace.yaml`
Using `npm install` in workspace packages	Always use `pnpm install` from the workspace root
Hardcoding versions duplicated across packages	Use `catalog:` to centralize version definitions
Running `pnpm install` inside a sub-package	Run from workspace root; use `--filter` to target packages
Expecting `--filter` to match directory names	`--filter` matches `package.json` `name` field, not directory names
Not escaping `!` in zsh for exclude filters	Use `\!` or quote the filter: `--filter="!foo"`
Using `workspace:` for non-workspace deps	`workspace:` protocol only works for packages defined in the workspace
Lifecycle scripts failing after pnpm 10 upgrade	pnpm 10 blocks scripts by default; add deps to `allowBuilds` in config
Using `pnpm deploy` without `inject-workspace-packages`	Set `inject-workspace-packages=true` in `.npmrc` (required in pnpm 10)

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

Delegation

任务委托

Workspace scaffolding: Use
```
Explore
```
agent to discover existing package structure
Dependency auditing: Use
```
Task
```
agent to check version consistency across packages

If the
turborepo
skill is available, delegate build orchestration, task caching, and CI optimization to it. If the
changesets
skill is available, delegate versioning, changelog generation, and npm publishing to it.

工作区脚手架搭建：使用Explore Agent探索现有包结构
依赖审计：使用Task Agent检查跨包的版本一致性

若
turborepo
Skill可用，将构建编排、任务缓存和CI优化委托给它。若
changesets
Skill可用，将版本管理、变更日志生成和npm发布委托给它。

References

参考资料

Workspace setup, workspace protocol, and catalogs
Filtering packages for targeted commands
Shared configuration across workspace packages
Monorepo integration: pnpm + Turborepo + Changesets pipeline

工作区设置、workspace协议和Catalogs
针对目标命令过滤包
跨工作区包共享配置
Monorepo集成：pnpm + Turborepo + Changesets流水线