工作空间(Workspace)
pnpm 内置了对单一存储库(也称为多包存储库、多项目存储库或单体存储库)的支持。 你可以创建一个工作空间以将多个项目合并到一个仓库中。
一个工作空间必须在它的根目录有一个 pnpm-workspace.yaml
文件。 工作区在其根目录中也可能有一个 .npmrc
。
如果你正在查看 monorpo 管理,那么你可能还希望查 看 Bit。
Bit 在后台使用 pnpm,但将许多当前在由 pnpm/npm/Yarn 管理的传统工作区中手动完成的事情自动化。 有一篇关于 bit install
的文章讨论了这一点:使用 Bit 进行无痛的 Monorepo 依赖管理。
工作空间协议 (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
+ ba
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"
}
}
这个功能允许你发布转化之后的包到远端,并且可以正常使用本地 workspace 中的 packages,而不需要其它中间步骤。包的使用者也可以像常规的包那样正常使用,且仍然可以受益于语义化版本。
发布工作流
workspace 中的包版本管理是一个复杂的任务,pnpm 目前也并未提供内置的解决方案。 不过,有两个不错且支持 pnpm 的版本控制工具可以使用:
有关如何使用 Rush 设置存储库,请阅读 此页面。
要使用 pnpm 的变更集,请阅读本指南。
问题排查
如果工作空间依赖项之间存在循环,则 pnpm 无法保证脚本将按拓扑顺序运行。 如果 pnpm 在安装过程中检测到循环依赖,则会提供一个 warning 警告。 如果 pnpm 能够找出导致循环的依赖项,也会将其展示出来。
如果你看到此消息 There are cyclic workspace dependencies
,请检查在 dependencies
, optionalDependencies
和 devDependencies
中声明的工作空间依赖。
使用示例
以下是几个使用了 pnpm 工作空间功能的最受欢迎的开源项目: