问题根源在于Project References未启用或composite配置缺失：需在被依赖包tsconfig.json中设"composite": true、"declaration": true，在消费包中通过"references"显式引用，并校验workspace路径、turborepo构建依赖、tsc --build验证及VS Code多根工作区配置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用Turborepo管理的大型monorepo中，发现TypeScript跨包引用失效、类型无法解析或IDE跳转指向.d.ts而非源码，则问题极可能源于Project References未正确启用或composite配置缺失。以下是针对该现象的多种分析与重构支持路径：
一、验证并启用Project References与composite配置
Project References是TypeScript原生支持monorepo跨包类型推断与增量编译的核心机制，必须在被引用包和引用包双方显式声明，且被引用包需设置composite: true以生成可被引用的项目元信息。
1、进入被依赖包（例如packages/ui）的tsconfig.json，确认已添加"composite": true字段，并确保"declaration": true和"outDir"存在或由构建工具隐式处理。
2、在该包的tsconfig.json中检查"include"是否覆盖源码路径（如["src/**/*"]），避免因路径排除导致TS无法识别有效源文件。
3、进入消费包（例如apps/web）的tsconfig.json，在"references"数组中添加对被依赖包的相对路径引用，格式为{"path": "../ui"}。
4、在消费包的tsconfig.json顶部添加"compilerOptions": {"composite": false}（非必需但推荐显式声明），并确保"incremental": true已启用。
二、校验pnpm workspace协议与路径映射一致性
pnpm的workspace:*链接虽能保证运行时模块解析，但TypeScript不直接消费node_modules中的符号链接；它依赖tsconfig.json中references路径与实际文件系统路径严格匹配，否则触发TS2307错误。
1、执行pnpm ls @repo/ui确认workspace包已被正确链接至node_modules。
2、检查消费包中import语句使用的包名（如@repo/ui）是否与被依赖包package.json中"name"字段完全一致。
3、在被依赖包的package.json中确认"types"字段指向正确的入口声明文件（如"types": "./dist/index.d.ts"），且该路径在构建后真实存在。
4、若使用自定义路径映射（如tsconfig.json中"baseUrl"与"paths"），需确保其不与workspace路径产生冲突，强烈建议在monorepo中禁用paths别名，改用标准workspace引用。
三、启用turborepo build任务级依赖图校验
Turborepo的pipeline依赖声明可强制构建顺序，间接暴露引用链断裂问题；通过定义明确的build依赖，可触发TS编译器提前报错，定位未配置references的包。
1、打开根目录turbo.json，在"pipeline"下为被依赖包（如ui）定义"build"任务，并设置"outputs"为["dist/**"]。
2、为消费包（如web）的"build"任务添加"dependsOn": ["ui#build"]，强制其等待ui构建完成。
3、运行turbo run build，观察是否出现TS2307或“Cannot find module”类错误；若出现，说明该消费包未正确定义references或被依赖包未生成有效类型输出。
4、检查turbo缓存日志中是否提示ui#build任务被跳过（cached）——若被跳过，可能因dist/已存在但内容陈旧，此时需手动删除dist目录后重试。
四、使用tsc --build进行独立项目级验证
脱离Turborepo运行原生tsc --build可绕过缓存与任务调度干扰，直击TS配置本身问题，是隔离诊断的关键手段。
1、切换至被依赖包目录（如cd packages/ui），执行tsc --noEmit --watch，确认无TS错误且能正常监听变更。
2、切换至消费包目录（如cd apps/web），执行tsc --noEmit --build，观察是否报告TS6305（project reference未找到）或TS6307（引用项目未启用composite）。
3、若报TS6305，检查消费包tsconfig.json中"references"所指路径是否为相对于该tsconfig.json的合法目录，不可使用node_modules/@repo/ui等运行时路径。
4、若报TS6307，返回被依赖包，确认其tsconfig.json中"composite": true位于顶层"compilerOptions"内，且无语法错误或JSON格式问题。
五、启用VS Code多根工作区与TypeScript Server重启
VS Code的TS语言服务默认按打开的文件夹启动，若仅打开子包目录，将无法感知根目录tsconfig.base.json或跨包references，导致跳转失败与错误高亮。
1、在VS Code中选择File → Add Folder to Workspace...，依次添加monorepo根目录及所有涉及的packages/和apps/子目录。
2、保存工作区为monorepo.code-workspace，确保"folders"数组包含全部相关路径。
3、按下Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入Typescript: Restart TS server并执行。
4、打开任意消费包中的TSX文件，尝试Cmd/Ctrl+点击导入的组件，确认是否跳转至packages/ui/src/下的源码而非dist/下的.d.ts文件；若仍跳转至.d.ts，请检查被依赖包tsconfig.json中是否遗漏"declarationMap": true。
