工作空间(Workspace)
pnpm 内置了对单一存储库(也称为多包存储库、多项目存储库或单体存储库)的支持。 你可以创建一个工作空间以将多个项目合并到一个仓库中。
工作空间的根目录下必须有 pnpm-workspace.yaml
文件, 工作区在其根目录中也可能有一个 .npmrc
文件。
如果你正在查看 monorpo 管理,那么你可能还希望 查看 Bit。 Bit 在后台使用 pnpm,但将许多当前在由 pnpm/npm/Yarn 管理的传统工作区中手动完成的事情自动化。 有一篇关于 bit install
的文章谈到了它: Painless Monorepo Dependency Management with Bit。
工作空间协议 (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
。 这种行为带来了一些不确定性。
幸运的是,pnpm 支持工作空间协议 workspace:
。 当使用此协议时,pnpm 将拒绝解析除本地工作空间所包含包之外的任何内容。 因此,如果你设置 "foo": "workspace:2.0.0"
,此时安装将失败,因为 "foo@2.0.0"
不存在于此工作空间中。
当 link-workspace-packages 选项被设置为 false
时,这个协议将特别有用。 在这种情况下,仅当使用 workspace:
协议声明依赖,pnpm 才会从此 workspace 链接所需的包。
通过别名引用工作空间包
假设你在工作空间中有一个名为 foo
的包。 通常你会像这样引用:"foo": "workspace:*"
。
如果要使用其他别名,那么以下语法也将起作用: "bar": "workspace:foo@*"
。
在发布之前,别名被转换为常规名称。 上面的示例将变为:"bar": "npm:foo@1.0.0"
。
通过相对路径引用工作空间包
假如工作空间中有 2 个包:
+ packages
+ foo
+ bar
bar
中可能有 foo
的依赖: "foo": "workspace:../foo"
。 在发布之前,这些将转换为所有包管理器支持的常规版本规范。
发布工作空间包
当工作被打包到归档(无论它是通过 pnpm pack
,还是 pnpm publish
之类的发布命令)时,我们将动态替换这些 workspace:
依赖:
- 目标工作空间中的对应版本(如果使用
workspace:*
,workspace:~
, orworkspace:^
) - 相关的语义化版本范围(对于任何其他范围类型)
看一个例子,假设我们的工作空间中有 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"
}
}
这个功能允许你发布转化之后的包到远端,并且可以正常使用本地 workspace 中的 packages,而不需要其它中间步骤。包的使用者也可以像常规的包那样正常使用,且仍然可以受益于语义化版本。
发布工作流
workspace 中的包版本管理是一个复杂的任务,pnpm 目前也并未提供内置的解决方案。 不过,有两个不错且支持 pnpm 的版本控制工具可以使用:
有关如何用 Rush 设置仓库,可以阅读 这篇文章。
有关在 pnpm 中使用 Changesets,可以阅读这篇指南。
故障排查
如果工作空间依赖项之间存在循环,则 pnpm 无法保证脚本将按拓扑顺序运行。 如果 pnpm 在安装过程中检测到循环依赖,则会提供一个 warning 警告。 如果 pnpm 能够找出导致循环的依赖项,也会将其 展示出来。
如果你看到此消息 There are cyclic workspace dependencies
,请检查在 dependencies
, optionalDependencies
和 devDependencies
中声明的工作空间依赖。
使用示例
以下是几个使用了 pnpm 工作空间功能的最受欢迎的开源项目: