跨包跳转失败的根本原因是 TypeScript 模块解析路径未对齐，需在根 tsconfig.json 的 paths 中映射包名到源码路径，并确保子包 tsconfig 启用 composite + references、VSCode 打开根工作区、重启 TS Server。
跨包跳转失败、import 补全找不到本地包，根本不是 VSCode 的问题，而是 TypeScript 没把 my-utils 这种包名映射到 packages/my-utils/src 的源码路径——只要配置没对齐，再重启十次 TS Server 也没用。
为什么 import { foo } from "my-utils" 跳不到定义，但 ../my-utils/src 可以？
这是典型的模块解析路径未对齐：TS 默认按 Node.js 规则去 node_modules/my-utils 找（那里只有构建产物），而你实际想链接的是 workspace 内的源码。
- 必须在根
tsconfig.json的compilerOptions.paths中显式声明映射，例如：{"my-utils": ["packages/my-utils/src"]} - 子包
packages/my-utils/tsconfig.json必须设"baseUrl": "./src"（或"."），确保和 paths 中的路径能对上 - 删掉
node_modules和.vscode缓存后，再执行pnpm install，否则旧解析缓存还在
打开工作区的方式错了，所有配置都白搭
VSCode 不会自动识别 pnpm 工作区，它只看你打开的是哪个文件夹。开错位置，TS Server 就只加载单个包上下文。
- 必须用 VSCode 打开含
pnpm-workspace.yaml的最外层目录，比如/my-monorepo，不能是/my-monorepo/packages/ui - 检查状态栏右下角：应显示 “TypeScript SDK: Workspace version”，若显示 “Project version” 或路径指向子包里的
node_modules/.pnpm/，说明识别失败 - 如果习惯进子包再执行
code .，请立刻退出，回到根目录重开：code /path/to/monorepo
子包 tsconfig 必须启用 composite + references
TypeScript 默认把每个 tsconfig.json 当独立项目，monorepo 需要它理解“这些包之间有依赖关系”，靠 references 和 composite: true 显式声明。
- 根
tsconfig.json加"references"数组，列出所有子包路径：[{ "path": "packages/my-utils" }, { "path": "apps/web" }] - 每个子包自己的
tsconfig.json必须含"composite": true，并"extends": "../tsconfig.base.json"（路径要准确） - 不要手动修改
node_modules/.pnpm下的 symlink 目标——那是 pnpm 自己管的，改了反而破坏类型解析
Path Intellisense 补全跨包路径要额外配 mappings
该插件不读取 tsconfig.json 的 paths，@/utils 这类别名必须手动告诉它映射关系，否则补全永远只在当前包内打转。
- 在
.vscode/settings.json或用户设置中加："path-intellisense.mappings": {"my-utils": "${workspaceFolder}/packages/my-utils/src"} - monorepo 场景下，启用
"path-intellisense.includePackageJson": true，并确保每个子包package.json有"main"或"types"字段（哪怕只是"types": "src/index.d.ts"） - 补全触发前提是：光标在字符串字面量内（如
import x from "）、editor.quickSuggestions.strings为true、语言模式正确（非 Plain Text）
最常被忽略的一点：改完 tsconfig.json 或重装依赖后，VSCode 不会自动刷新 TS Server。Ctrl+Shift+P → 输入 Restart TS server 是硬性步骤，不是可选项。
