pnpm monorepo下TS无法找到间接依赖模块声明如何解决

API 探路者

2026-9-1

问题现象

当前主模块未直接引入@tiptap/extension-highlight，该依赖由外部模块引入。

问题说明

apps/demo 模块需要使用@tiptap/extension-highlight的类型，但该依赖仅在公共组件模块的components/tiptap/src/extensions/TipTapWordStarterKit.ts中引入，主模块无法识别该间接依赖的类型。

补充背景

pnpm + monorepo 架构下，TypeScript 对间接依赖的类型识别属于已知问题，TypeScript 官方仓库已有多个相关issue记录。

解决方案

按推荐优先级从高到低排列：

方案1：在使用方模块显式声明依赖（官方推荐，无副作用）
pnpm 默认采用严格依赖隔离设计，要求每个包必须显式声明自身用到的所有依赖，禁止直接使用其他包引入的幽灵依赖。直接在 apps/demo 模块中安装对应版本的@tiptap/extension-highlight到开发依赖即可，执行命令：
```
pnpm add -D @tiptap/extension-highlight --filter apps/demo
```
注意安装版本需和公共组件模块中使用的版本保持一致，避免多版本冲突。
方案2：配置TS路径映射（无需重复安装依赖）
如果不想重复安装依赖，可在 apps/demo 对应的tsconfig.json中配置paths字段，手动指向依赖的实际存放路径：
```
{
  "compilerOptions": {
    "paths": {
      "@tiptap/extension-highlight": ["../../components/tiptap/node_modules/@tiptap/extension-highlight"]
    }
  }
}
```
该方案需要手动维护路径配置，后续依赖位置、版本变动时需同步修改。
方案3：配置pnpm依赖提升（临时兜底，不推荐长期使用）
在项目根目录的.npmrc文件中添加配置，将对应依赖提升到根目录node_modules，供所有包全局访问：
```
public-hoist-pattern[]=@tiptap/extension-highlight
```
配置完成后重新执行pnpm install即可生效。该方案会破坏pnpm的依赖隔离机制，容易引发多版本依赖冲突，仅适合临时调试场景。