Yarn Workspace Zero Install+PnP模式下如何调用根目录依赖命令

问题本质 #

Yarn 3.x 启用PnP+Zero Install时，默认开启严格依赖边界隔离：每个工作区仅能访问自身package.json中显式声明的依赖，和传统node_modules模式下依赖被提升、子包可隐式访问根目录依赖的逻辑完全不同。直接在子包内执行裸tsc命令、或在子包脚本中直接写tsc时，Yarn不会主动遍历根目录依赖查找二进制，因此触发命令不存在报错。

可落地解决方法 #

按推荐优先级排序：

方法1：使用top-level参数直接调用根级二进制（零配置首选） #

不需要修改依赖声明、不需要额外配置，直接利用Yarn内置参数强制从根工作区查找二进制即可。
在packages/package-a/package.json的build脚本中配置：

{
  "scripts": {
    "build": "yarn run -T tsc"
  }
}

-T是--top-level的缩写，作用是忽略当前子工作区的依赖列表，直接从根工作区的依赖中查找匹配的二进制，100%使用根目录package.json声明的TypeScript版本。
如果手动进入packages/package-a目录需要临时执行tsc，直接在终端输入yarn run -T tsc即可，无需全局安装。

方法2：直接指定二进制实际路径 #

PnP模式下可以直接获取二进制在缓存中的实际路径调用，不需要依赖Yarn的依赖查找逻辑：

• 先在项目根目录执行yarn bin tsc，会直接输出tsc的实际存储路径，格式类似.yarn/cache/typescript-npm-5.2.2-abc123.zip/node_modules/typescript/bin/tsc
• 子包脚本中可以直接写这个路径，更通用的无硬编码写法如下，执行时会自动替换为实际路径：

{
  "scripts": {
    "build": "node $(yarn bin tsc)"
  }
}

注意：路径前必须加node调用，PnP模式下zip包内的可执行文件无法直接被系统识别执行，通过node触发时Yarn会自动注入PnP运行环境，保证依赖解析正常。

方法3：配置公共依赖全局可用（适合多公共依赖场景） #

如果除TypeScript外，还有ESLint、Prettier等多个公共依赖需要给所有子包使用，不想每个脚本都加-T参数，可以在根目录.yarnrc.yml中添加如下配置，给所有子包隐式添加根级公共依赖的访问权限：

packageExtensions:
  "*":
    dependencies:
      typescript: "*"

配置完成后执行yarn install刷新PnP映射表，之后所有子包的脚本中直接写tsc、或者在任意子包目录执行yarn run tsc都可以正常调用根目录的TypeScript版本。

PnP模式下依赖二进制的调用逻辑 #

和传统node_modules模式的软链逻辑完全不同，PnP的二进制执行流程如下：

• 所有依赖以zip格式存储在.yarn/cache目录，全程不会解压到项目目录，也不会生成任何层级的node_modules目录、以及node_modules/.bin软链目录。
• 执行yarn install时，Yarn会在根目录生成.pnp.cjs文件，里面维护三份核心映射：所有依赖在缓存zip包内的具体位置、每个工作区允许访问的依赖范围、每个依赖提供的二进制文件路径。
• 执行yarn run <命令>时，Yarn会先查询当前工作区的可访问依赖列表，匹配到对应二进制的缓存路径后，自动注入PnP运行时环境执行，不需要将二进制添加到系统全局PATH。
• 直接在终端输入裸命令（比如不带yarn前缀的tsc）时，系统会从全局PATH查找命令，自然找不到仅存在于项目缓存中的二进制，这也是初始报错的核心原因。

内容的提问来源于stack exchange，提问作者Dac0d3r