Version: 9.x

工作区

pnpm 内置了对单一存储库（也称为多包存储库、多项目存储库或整体存储库）的支持。你可以创建一个工作区来将多个项目联合到一个存储库中。

¥pnpm has built-in support for monorepositories (AKA multi-package repositories, multi-project repositories, or monolithic repositories). You can create a workspace to unite multiple projects inside a single repository.

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

¥A workspace must have a pnpm-workspace.yaml file in its root. A workspace also may have an .npmrc in its root.

提示

如果你正在研究 monorepo 管理，你可能还想研究 Bit。Bit 在底层使用 pnpm，但会自动执行当前在 pnpm/npm/Yarn 管理的传统工作区中手动完成的许多事情。有一篇关于 bit install 的文章谈到了它：使用 Bit 进行无痛 Monorepo 依赖管理。

¥If you are looking into monorepo management, you might also want to look into Bit. Bit uses pnpm under the hood but automates a lot of the things that are currently done manually in a traditional workspace managed by pnpm/npm/Yarn. There's an article about bit install that talks about it: Painless Monorepo Dependency Management with Bit.

工作区协议（工作区：）

¥Workspace protocol (workspace:)

如果 link-workspace-packages 设置为 true，如果可用包与声明的范围匹配，pnpm 将从工作区链接包。例如，如果 bar 在其依赖中有 "foo": "^1.0.0" 并且 foo@1.0.0 在工作区中，则 foo@1.0.0 链接到 bar。但是，如果 bar 在依赖中有 "foo": "2.0.0"，并且 foo@2.0.0 不在工作区中，则将从注册表安装 foo@2.0.0。这种行为带来了一些不确定性。

¥If link-workspace-packages is set to true, pnpm will link packages from the workspace if the available packages match the declared ranges. For instance, foo@1.0.0 is linked into bar if bar has "foo": "^1.0.0" in its dependencies and foo@1.0.0 is in the workspace. However, if bar has "foo": "2.0.0" in dependencies and foo@2.0.0 is not in the workspace, foo@2.0.0 will be installed from the registry. This behavior introduces some uncertainty.

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

¥Luckily, pnpm supports the workspace: protocol. When this protocol is used, pnpm will refuse to resolve to anything other than a local workspace package. So, if you set "foo": "workspace:2.0.0", this time installation will fail because "foo@2.0.0" isn't present in the workspace.

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

¥This protocol is especially useful when the link-workspace-packages option is set to false. In that case, pnpm will only link packages from the workspace if the workspace: protocol is used.

通过别名引用工作区包

¥Referencing workspace packages through aliases

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

¥Let's say you have a package in the workspace named foo. Usually, you would reference it as "foo": "workspace:*".

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

¥If you want to use a different alias, the following syntax will work too: "bar": "workspace:foo@*".

在发布之前，别名将转换为常规别名依赖。上面的例子将变成："bar": "npm:foo@1.0.0"。

¥Before publish, aliases are converted to regular aliased dependencies. The above example will become: "bar": "npm:foo@1.0.0".

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

¥Referencing workspace packages through their relative path

在有 2 个包的工作区中：

¥In a workspace with 2 packages:

+ packages
	+ foo
	+ bar

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

¥bar may have foo in its dependencies declared as "foo": "workspace:../foo". Before publishing, these specs are converted to regular version specs supported by all package managers.

发布工作区包

¥Publishing workspace packages

当工作区包打包到存档中时（无论是通过 pnpm pack 还是像 pnpm publish 这样的发布命令之一），我们通过以下方式动态替换任何 workspace: 依赖：

¥When a workspace package is packed into an archive (whether it's through pnpm pack or one of the publish commands like pnpm publish), we dynamically replace any workspace: dependency by:

目标工作区中的相应版本（如果你使用 workspace:*、workspace:~ 或 workspace:^）

¥The corresponding version in the target workspace (if you use workspace:*, workspace:~, or workspace:^)
关联的 semver 范围（对于任何其他范围类型）

¥The associated semver range (for any other range type)

例如，如果工作区中有 foo、bar、qar、zoo，它们的版本均为 1.5.0，则如下：

¥So for example, if we have foo, bar, qar, zoo in the workspace and they all are at version 1.5.0, the following:

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

将转化为：

¥Will be transformed into:

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

此功能允许你依赖本地工作区包，同时仍然能够将生成的包发布到远程注册表，而无需中间发布步骤 - 你的消费者将能够像使用任何其他包一样使用你发布的工作区，同时仍然受益于 semver 提供的保证。

¥This feature allows you to depend on your local workspace packages while still being able to publish the resulting packages to the remote registry without needing intermediary publish steps - your consumers will be able to use your published workspaces as any other package, still benefitting from the guarantees semver offers.

发布工作流程

¥Release workflow

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

¥Versioning packages inside a workspace is a complex task and pnpm currently does not provide a built-in solution for it. However, there are 2 well tested tools that handle versioning and support pnpm:

changesets
Rush。

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

¥For how to set up a repository using Rush, read this page.

要通过 pnpm 使用变更集，请阅读本指南。

¥For using Changesets with pnpm, read this guide.

故障排除

¥Troubleshooting

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

¥pnpm cannot guarantee that scripts will be run in topological order if there are cycles between workspace dependencies. If pnpm detects cyclic dependencies during installation, it will produce a warning. If pnpm is able to find out which dependencies are causing the cycles, it will display them too.

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

¥If you see the message There are cyclic workspace dependencies, please inspect workspace dependencies declared in dependencies, optionalDependencies and devDependencies.