必须用根目录打开 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

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 在项目根目录建 .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 映射。其他所有配置，都是在这两个前提上才起作用。