pnpm 的 workspace 协议允许在子包的 package.json 中写入 dependencies 字段并使用 workspace:* 或 workspace:^ 来引用本地包。pnpm 会为这些依赖创建指向工作区目录的符号链接，从而避免重复安装。对于纯 JavaScript 包来说，这种机制通常没有问题，但 TypeScript 在解析类型入口时却可能因为符号链接、types 字段、exports 映射以及模块解析策略的差异而报错。本文从常见报错表现说起，分析 workspace 环境下类型解析失效的根因，并给出几种可落地的修复方案。
一、问题表现与根因定位
在 pnpm monorepo 中，如果本地包 @repo/utils 的 package.json 只写了 main 字段但没有 types 字段，或者 types 指向的 .d.ts 文件尚未生成，TypeScript 在编译引用该包的项目时会报 TS7016：无法找到模块“@repo/utils”的声明文件，隐式拥有 any 类型。另一种常见情况是包使用了 exports 字段，但 exports 中没有为 types 条件提供映射，某些 moduleResolution 策略会直接忽略 types 字段而只读取 exports，导致虽然 dist 目录下有 .d.ts 文件，编译器依然找不到类型。
造成这些现象的核心原因通常有三个。第一，workspace 包处于开发状态，源码未构建，dist 目录不存在；如果 package.json 的类型入口指向 dist 下的声明文件，TypeScript 自然无法解析。第二，exports 字段配置不完整，缺少 types 条件或条件顺序错误，导致解析器匹配到了错误的入口。第三，tsconfig 的 moduleResolution 与目录结构不匹配，例如使用 NodeNext 解析时要求 exports 字段严格定义，使用 classic 解析时又完全忽略 exports，很容易出现行为不一致。下面这段配置就是典型的“依赖构建产物但未构建”的情况。
{
"name": "@repo/utils",
"version": "1.0.0",
"main": "./dist/index.js",
"types": "./dist/index.d.ts"
}
如果这个包还没有执行构建脚本，dist 目录不存在，那么引用方的 TypeScript 编译器在查找 @repo/utils 时只能得到 main 对应的 JS 入口，类型声明缺失，于是报出 TS7016。这只是问题的一种，接下来我们针对不同场景给出对应解法。
二、方案一：规范 package.json 的 types 与 exports 映射
对于已经构建产物的包，最直接的修复是把 exports 字段补全，并且把 types 条件放在最前面。exports 中的条件顺序非常重要，TypeScript 会按照顺序匹配条件，如果 types 被放在 import 之后，某些解析器可能先命中 import 而忽略类型。因此推荐将 types 放在每个入口的第一位。同时保留顶层 types 字段以兼容较旧的 TypeScript 版本和工具链。
{
"name": "@repo/utils",
"version": "1.0.0",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js",
"require": "./dist/index.cjs"
}
},
"files": ["dist"]
}
做完这一步后，建议重新运行 pnpm install 并执行构建，确保 dist 目录中的 .d.ts 文件与 package.json 中声明的路径完全一致。如果你使用 turbo 或 nx 编排 monorepo 任务，还可以把依赖包的 build 配置为引用包 dev 的前置任务，避免出现类型文件未生成就开始类型检查的情况。
如果希望在开发模式下不构建也能解析类型，可以在 tsconfig 中使用 paths 将包名映射到源码目录。例如根 tsconfig.json 中添加如下配置，可以绕过 node_modules 解析，直接读取 TypeScript 源码。
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@repo/utils": ["packages/utils/src/index.ts"],
"@repo/utils/*": ["packages/utils/src/*"]
}
}
}
paths 方案的优势是编辑器响应快，适合源码驱动开发。但它只在编译期生效，运行时仍然需要 pnpm 的符号链接支持。如果同时使用了 exports，paths 的优先级取决于配置，建议在开发模式下配合 ts-node 或 bundler 的 alias 使用。此方案不太适合库发布场景，因为发布后包的路径会变化，paths 映射会失效。
三、方案二：启用 TypeScript Project References 直接引用源码
对于不想预先构建每个包、希望编辑器和 tsc 都能直接识别源码类型的 monorepo，TypeScript Project References 是更彻底的方案。它通过 references 关联包与包之间的依赖，要求被引用的包开启 composite 和 declaration 选项，rootDir、outDir 配置一致。这样当执行 tsc --build 时，TypeScript 会按依赖顺序增量编译并生成声明文件；在 IDE 中，引用方可以跳转到源码定义，而不是查看 dist。
先来看根 tsconfig.json 的配置，它本身不编译任何文件，只负责声明工作区中有哪些子项目。
{
"files": [],
"references": [
{ "path": "./packages/utils" },
{ "path": "./apps/web" }
]
}
工具包 packages/utils 的 tsconfig.json 需要开启 composite 与 declaration，并明确 rootDir 和 outDir，这样项目引用才能正确生成声明文件。
{
"compilerOptions": {
"composite": true,
"declaration": true,
"declarationMap": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src"]
}
应用包 apps/web 在 references 中指向工具包，同时自身也开启 composite，以便被其他项目引用时能提供声明。
{
"compilerOptions": {
"composite": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src"],
"references": [
{ "path": "../../packages/utils" }
]
}
完成以上配置后，在根目录执行 tsc --build 而不是直接运行 tsc。--build 模式会按照 references 的拓扑顺序编译所有相关项目，遇到已经编译且未变更的项目会跳过，速度更快。如果你在 VS Code 中工作，确保打开的是根目录的 tsconfig.json 所在的工作区，这样语言服务才能识别项目引用关系。需要注意的是，每个被引用的项目都必须设置 composite: true，否则 TypeScript 会报 TS6306 错误。
Project References 与前面提到的 paths 并不冲突，它们可以共存：references 解决构建顺序和声明生成，paths 解决模块解析。但要注意两者指向的路径必须一致，否则可能出现编辑器识别到源码类型，而 tsc --build 却生成到错误 dist 的情况。
四、方案三：调整 pnpm 的依赖提升与安装行为
有时类型引用失败与 package.json 配置无关，而是 pnpm 的 node_modules 结构导致 TypeScript 在解析传递依赖时找不到类型包。pnpm 默认使用符号链接的半严格模式，只有显式声明的依赖会出现在包自己的 node_modules 中，未声明的传递依赖不会提升。如果某个包的类型定义依赖了未声明的 @types/node 或其他类型包，就可能出现 TS2688 找不到类型声明文件。
解决思路不是盲目开启 shamefully-hoist，因为它会把所有依赖都提升到根目录，破坏 pnpm 的隔离优势。更推荐依据类型声明缺失的具体包，在 package.json 中显式补充依赖，或者使用 pnpm 的 public-hoist-pattern 只提升与类型相关的包。例如在根目录的 .npmrc 中添加以下配置。
public-hoist-pattern[]=*types* public-hoist-pattern[]=@types/*
这样 pnpm 只会把名称中包含 types 的包提升到根目录，减少影响范围，同时让 TypeScript 更容易发现公共类型声明。配置后需要重新运行 pnpm install 才能生效。
另外，如果 workspace 包之间出现重复类型实例，例如 React 类型被多个包私有安装，可能导致类型不兼容，此时可以通过 pnpm dedupe 或统一在根 package.json 中放置公共依赖来解决。安装后若符号链接失效，运行 pnpm install --force 或 pnpm install --fix-lockfile 能刷新节点，再配合编辑器重启或重新加载窗口，通常可以恢复类型提示。
五、验证与小结
在完成上述任一方案后，建议在引用包的 tsconfig 中开启 noImplicitAny 和 skipLibCheck false 来暴露潜在类型问题。skipLibCheck 默认是 false，但如果之前为了解决第三方类型冲突而改为 true，会让部分本地声明错误被隐藏。运行 tsc --noEmit 做纯类型检查，能在不产出文件的情况下快速验证。最后在 IDE 中按住 Ctrl 或 Command 点击模块名，如果跳转到源码或正确的 d.ts 文件，就说明类型解析已经恢复。
pnpm workspace 的类型引用问题大多集中在 package.json 的入口字段和 TypeScript 的解析策略上，而不是 pnpm 本身。只要把 types 和 exports 的映射关系维护好，再根据开发模式选择 paths 或 Project References，必要时微调 pnpm 的提升策略，就能在保持 monorepo 包隔离性的同时获得稳定的类型体验。
TypeScript类型定义pnpm workspaceworkspace协议修改时间：2026-10-01 03:50:28