跳至主要内容
版本: 9.x

工作区

pnpm 内置支持单仓库（又称多包仓库、多项目仓库或单体仓库）。您可以创建一个工作区，将多个项目整合到一个仓库中。

工作区必须在其根目录中有一个 pnpm-workspace.yaml 文件。工作区也可能在其根目录中有一个 .npmrc 文件。

提示

如果您正在研究单仓库管理，您可能还想了解 Bit。Bit 在底层使用 pnpm，但自动化了许多目前在由 pnpm/npm/Yarn 管理的传统工作区中手动完成的任务。有一篇关于 bit install 的文章对此进行了介绍：使用 Bit 实现无忧的单仓库依赖管理。

工作区协议 (workspace:)​

默认情况下，如果可用包与声明的范围匹配，pnpm 将链接工作区中的包。例如，如果 bar 的依赖项中包含 "foo": "^1.0.0" 并且 [email protected] 位于工作区中，则 [email protected] 将被链接到 bar。但是，如果 bar 的依赖项中包含 "foo": "2.0.0" 并且 [email protected] 不在工作区中，则 [email protected] 将从注册表中安装。这种行为会带来一些不确定性。

幸运的是，pnpm 支持 workspace: 协议。使用此协议时，pnpm 将拒绝解析为除本地工作区包以外的任何内容。因此，如果您设置 "foo": "workspace:2.0.0"，这次安装将失败，因为 "[email protected]" 不存在于工作区中。

当 link-workspace-packages 选项设置为 false 时，此协议特别有用。在这种情况下，pnpm 仅在使用 workspace: 协议时才会链接工作区中的包。

通过别名引用工作区包​

假设您在工作区中有一个名为 foo 的包。通常，您会将其引用为 "foo": "workspace:*"。

如果您想使用不同的别名，以下语法也适用："bar": "workspace:foo@*"。

在发布之前，别名将转换为常规的别名依赖项。上面的示例将变为："bar": "npm:[email protected]"。

通过其相对路径引用工作区包​

在一个包含 2 个包的工作区中

+ packages
	+ foo
	+ bar

bar 可能在其依赖项中声明 foo 为 "foo": "workspace:../foo"。在发布之前，这些规范将转换为所有包管理器支持的常规版本规范。

发布工作区包​

当工作区包被打包到存档中（无论是通过 pnpm pack 还是通过发布命令（如 pnpm publish））时，我们会动态地将任何 workspace: 依赖项替换为

  • 目标工作区中的对应版本（如果您使用 workspace:*、workspace:~ 或 workspace:^）
  • 关联的语义化版本范围（对于任何其他范围类型）

例如，如果我们在工作区中拥有 foo、bar、qar、zoo，并且它们都处于 1.5.0 版本，则以下内容

{
	"dependencies": {
		"foo": "workspace:*",
		"bar": "workspace:~",
		"qar": "workspace:^",
		"zoo": "workspace:^1.5.0"
	}
}

将转换为

{
	"dependencies": {
		"foo": "1.5.0",
		"bar": "~1.5.0",
		"qar": "^1.5.0",
		"zoo": "^1.5.0"
	}
}

此功能允许您依赖本地工作区包，同时仍然能够将生成的包发布到远程注册表，而无需中间发布步骤 - 您的使用者将能够像使用任何其他包一样使用您发布的工作区，并且仍然可以从语义化版本提供的保证中获益。

发布流程​

对工作区内的包进行版本控制是一项复杂的任务，pnpm 目前没有提供内置解决方案。但是，有 2 个经过良好测试的工具可以处理版本控制并支持 pnpm

有关如何使用 Rush 设置仓库，请阅读 此页面。

有关将 Changesets 与 pnpm 一起使用，请阅读 本指南。

故障排除​

如果工作区依赖项之间存在循环，pnpm 无法保证脚本将按拓扑顺序运行。如果 pnpm 在安装过程中检测到循环依赖项，它将发出警告。如果 pnpm 能够找出导致循环的依赖项，它也会显示它们。

如果您看到消息 There are cyclic workspace dependencies，请检查 dependencies、optionalDependencies 和 devDependencies 中声明的工作区依赖项。

使用示例​

以下是一些使用 pnpm 工作区功能的最受欢迎的开源项目

项目星标迁移日期迁移提交
Next.js2022-05-29f7b81316aea4fc9962e5e54981a6d559004231aa
Material UI2024-01-03a1263e3e5ef8d840252b4857f85b33caa99f471d
Vite2021-09-263e1cce01d01493d33e50966d0d0fd39a86d229f9
Nuxt2022-10-1774a90c566c936164018c086030c7de65b26a5cb6
Vue 3.02021-10-0961c5fbd3e35152f5f32e95bf04d3ee083414cecb
Astro2022-03-08240d88aefe66c7d73b9c713c5da42ae789c011ce
n8n2022-11-09736777385c54d5b20174c9c1fda38bb31fbf14b4
Prisma2021-09-21c4c83e788aa16d61bae7a6d00adc8a58b3789a06
Slidev2021-04-12d6783323eb1ab1fc612577eb63579c8f7bc99c3a
Turborepo2022-03-02fd171519ec02a69c9afafc1bc5d9d1b481fba721
Ember.js2023-10-18b6b05da662497183434136fb0148e1dec544db04
Element Plus2021-09-23f9e192535ff74d1443f1d9e0c5394fad10428629
NextAuth.js2022-05-034f29d39521451e859dbdb83179756b372e3dd7aa
Qwik2022-11-14021b12f58cca657e0a008119bc711405513e1ee9
VueUse2021-09-25826351ba1d9c514e34426c85f3d69fb9875c7dd9
SvelteKit2021-09-26b164420ab26fa04fd0fbe0ac05431f36a89ef193
Verdaccio2021-09-219dbf73e955fcb70b0a623c5ab89649b95146c744
Vercel2023-01-129c768b98b71cfc72e8638bf5172be88c39e8fa69
Vitest2021-12-13d6ff0ccb819716713f5eab5c046861f4d8e4f988
Cycle.js2021-09-21f2187ab6688368edb904b649bd371a658f6a8637
Milkdown2021-09-264b2e1dd6125bc2198fd1b851c4f00eda70e9b913
Nhost2022-02-0710a1799a1fef2f558f737de3bb6cadda2b50e58f
Logto2021-07-290b002e07850c8e6d09b35d22fab56d3e99d77043
Rollup 插件2021-09-2153fb18c0c2852598200c547a0b1d745d15b5b487
icestark2021-12-164862326a8de53d02f617e7b1986774fd7540fccd
ByteMD2021-02-1836ef25f1ea1cd0b08752df5f8c832302017bb7fb