必须用根目录打开 monorepo 项目并重启 TS Server，否则 VSCode 无法识别完整结构、turbo 命令不可用、Ctrl+Click 跳转本地包失败；所有配置均以此为前提。
VSCode 里看不到 monorepo 的完整结构、turbo 命令报 command not found、Ctrl+Click 跳转本地包失败——这些问题不是 VSCode 不行，而是你没用对打开方式和配置逻辑。
必须用根目录打开项目，否则一切配置都白搭
VSCode 不会自动识别你“想”打开的是 monorepo。它只认你实际点击打开的路径。如果你双击进了 packages/ui 或 apps/web，那它就只当这是一个普通单包项目。
- 确认资源管理器顶部显示的是
文件夹:/my-monorepo（或类似根路径），而不是更深层的子目录 - 检查根目录是否存在
pnpm-workspace.yaml（pnpm）、turbo.json或lerna.json；如果用 pnpm，该文件必须格式合法，例如：packages: - 'apps/*' - 'packages/*'
- 别用多根工作区（
.code-workspace）强行拼凑多个子包——这会绕过 workspace 协议解析，导致 TS 跳转和 turbo 依赖分析失效
VSCode 终端里 turbo 找不到？不是没装，是 PATH 没导进去
turbo 默认只安装在 monorepo 根目录的 node_modules/.bin，而 VSCode 启动终端时并不会自动把当前项目的 ./node_modules/.bin 加进 PATH。
- 先运行
npx turbo --version：能输出版本号 → 说明 turbo 已装好，纯属环境路径问题 - 检查 VSCode 设置中
terminal.integrated.defaultProfile是否指向你日常用的 shell（如zsh或bash）；Windows 用户尤其注意别设成 PowerShell - 在 shell 配置文件（如
~/.zshrc）末尾加：export PATH="./node_modules/.bin:$PATH"（⚠️必须是./，不是$PWD/或绝对路径） - 更稳妥的做法：所有命令都用
npx turbo，彻底绕过 PATH 依赖
tasks.json 配置 turbo run，别写死命令或依赖全局安装
VSCode 的任务系统不参与 turbo 的依赖拓扑解析，它只负责触发。硬写 turbo run build 或假设 turbo 全局可执行，会在换机器、换 shell、CI 环境下直接崩。
- 在项目根目录建
.vscode/tasks.json，type设为"shell"，command写"npx turbo run build" - 加
"group": "build"，这样按Cmd/Ctrl+Shift+B就能唤出构建菜单 - 要只构建某个包，比如
packages/ui，加参数："npx turbo run build --scope=ui" - 别在
dependsOn字段里写跨包依赖——那是turbo.json的pipeline干的事，VSCode 任务不理解这个语义
Ctrl+Click 跳转本地包失败？TypeScript 根本不知道去哪找
monorepo 里没有真实的 node_modules/my-utils 目录，只有通过 paths 映射或 workspace 协议暴露的源码。TS Server 若没加载正确的配置，就会当成缺失模块。
- 根目录要有
tsconfig.base.json（或类似基础配置），里面定义"baseUrl": "."和"paths"，例如："my-utils": ["packages/my-utils/src"] - 每个子包的
tsconfig.json必须"extends": "../tsconfig.base.json"，且含"composite": true - 删掉所有子包下的
node_modules和锁文件，再执行pnpm install重装 - 改完配置后，必须手动重启 TS Server：快捷键
Cmd/Ctrl+Shift+P→ 输入Restart TS Server
最容易被忽略的其实是「打开方式」和「TS Server 重启」这两步——前者决定了 VSCode 能不能看见整个 monorepo，后者决定了它能不能理解你写的 paths 映射。其他所有配置，都是在这两个前提上才起作用。
