跳到主内容
Version: 6.x

工作空间

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

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

工作空间协议 (workspace:)​

添加于： v3.7.0.

默认情况下，如果可用的packages与已声明的可用范围相匹配，pnpm 将从工作区链接这些packages。 例如，如果 bar 中有 "foo"："^1.0.0" 的这个依赖项，则 foo@1.0.0 链接到 bar 。 但是，如果 bar 的依赖项中有"foo": "2.0.0" ，而foo@2.0.0 在工作空间中并不存在，则将从npm registry安装foo@2.0.0 。 这种行为带来了一些不确定性。

幸运的是，pnpm 支持工作空间协议 workspace: 。 当使用此协议时，pnpm 将拒绝解析除本地工作区 package 之外的任何内容。 因此，如果您设置为 "foo": "workspace:2.0.0" 时，安装将会失败，因为 "foo@2.0.0" 不存在于工作空间中。

当 link-workspace-packages 选项 设置为 false时，这个协议就尤其有用。 在这种情况下，仅当使用 workspace:协议声明依赖，pnpm 才会从工作空间链接所需的包。

通过别名引用工作空间包​

添加于：v5.12.0

假设您在工作区有一个名为 foo 的包。 通常你会像这样引用："foo": "workspace:*"。

如果要使用其他别名，那么以下语法也将起作用: "bar": "workspace:foo@*"。

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

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

添加于：v5.12.0

工作区内有两个软件包：

+ packages
    + foo
    + bar

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

发布工作空间包​

当工作空间包打包到归档（无论它是通过 pnpm pack ，还是 pnpm publish 之类的发布命令）时，我们将动态替换这些 workspace: 依赖:

  • 目标工作空间中的对应版本（如果使用 workspace:*, workspace:~, or workspace:^）
  • 相关的 semver 范围（对于任何其他范围类型）

因此，例如，如果我们的工作空间中有 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"
    }
}

这个功能允许您可以发布转化之后的包到远端，并且可以正常使用本地工作空间的 packages，而不需要其它中间步骤。包的使用者也可以像常规的包那样正常使用，且仍然可以受益于语义化版本。

发布工作空间 (release workspace)​

工作空间内的 packages 的版本管理是个十分复杂的任务， pnpm暂未支持内置的解决方案。 不过，有两个测试完好的工具可以处理版本管理且支持 pnpm ：

有关如何用 Rush 建立仓库，请阅读这篇文章。

有关在 pnpm 中使用Changesets ，请阅读这里。

配置项​

添加于：v2.14.0

  • 默认值： true
  • 类型: true, false, deep

如果启用了此选项，本地可用的packages将被链接到 node_modules 中而不是从注册表下载。 这在 monorepo 项目中使用起来将十分方便。 如果您需要将本地 packages 也链接到子依赖项，则可以设置为 deep （自 v5 版本起）。

否则， packages 将全部从注册表下载并安装。 不过，工作空间的 packages 仍然可以通过 workspace: 范围协议被链接到。

prefer-workspace-packages​

添加于： v5.13.0

  • 默认值： false
  • 类型：Boolean

如果启用了此选项，工作空间中的本地 package 将优先于注册表，即使注册表中有了该 package 的新版本。

该设置只在工作空间未开启 save-workspace-protocol 时有效。

shared-workspace-lockfile​

添加于：v2.17.0 为 shared-workspace-shrinkwrap减

  • 默认值： true
  • 类型：Boolean

如果启用此选项，pnpm 会在工作空间的根目录中创建一个唯一的 pnpm-lock.yaml 文件。 这也意味着工作空间的packages的所有依赖项都将位于单个 node_modules 中。（同时软链接到它们packages 的 node_modules 文件夹中用于 Node 的模块解析）。

此选项的好处：

  • 每个依赖都是一个单例
  • 在 monorepo 中的安装更快
  • 代码更改都在一个文件中、代码审查（Cr ）减少

::: 注意

尽管所有依赖项都将硬链接到根 node_modules 中，但packages 只能访问 package.json 中声明的 ，因此 pnpm 的严格性得以保留。 这是上述软链接的效果。

:::

save-workspace-protocol​

  • 默认值： true
  • 类型：Boolean

如果启用此选项，新的依赖将会被工作空间协议 workspace:添加，当且仅当依赖存在于工作空间时。

如果您项目中的工具不支持工作空间协议，您可能希望将此设置更改为 false（最好提交一个 PR 让其在后续可以支持）。

故障排查​

如果工作空间依赖项之间存在循环，则 pnpm 无法保证脚本将按拓扑顺序运行。 如果 pnpm 在安装过程中检测到循环依赖，则会提供一个 warning 警告。 如果 pnpm 能够找出导致循环的依赖项，也会将其展示出来。

如果您看到此消息 There are cyclic workspace dependencies ，请检查在dependencies, optionalDependencies 和 devDependencies 中声明的工作空间依赖。

用法示例​

以下是几个使用了 pnpm 工作空间功能的开源项目：

  • icestark (截至 12/16/2021, commit 4862326a8de53d02f617e7b1986774fd7540fccd)
  • Vue 3.0 (截至 10/9/2021, commit 61c5fbd3e35152f5f32e95bf04d3ee083414cecb)
  • Vite (截至9/26/2021, commit 3e1cce01d01493d33e50966d0d0fd39a86d229f9)
  • Cycle.js (截至 9/21/2021, commit f2187ab6688368edb904b649bd371a658f6a8637)
  • Prisma (截至 9/21/2021, commit c4c83e788aa16d61bae7a6d00adc8a58b3789a06)
  • Verdaccio (截至 9/21/2021, commit 9dbf73e955fcb70b0a623c5ab89649b95146c744)
  • Rollup plugins (截至 9/21/2021, commit 53fb18c0c2852598200c547a0b1d745d15b5b487)
  • Milkdown (截至 9/26/2021, commit 4b2e1dd6125bc2198fd1b851c4f00eda70e9b913)
  • ByteMD (截至 2/18/2021, commit 36ef25f1ea1cd0b08752df5f8c832302017bb7fb)
  • VueUse (截至 9/25/2021, commit 826351ba1d9c514e34426c85f3d69fb9875c7dd9)
  • Slidev (截至 4/12/2021, commit d6783323eb1ab1fc612577eb63579c8f7bc99c3a)
  • SvelteKit (截至 9/26/2021, commit b164420ab26fa04fd0fbe0ac05431f36a89ef193)
  • Telecraft (截至 9/26/2021, commit 73a9c48c9d4f160d758b8881f404cc52c20a7454)
  • GiraphQL (截至 8/4/2021, commit 3dd3ff148da382d6f406f20626a9a5c25707c0c8)
  • Tailchat (截至 12/27/2021, commit 298af71aa0619e0a8fa8717777afe2fb32739db4)