VSCode中turbo命令报command not found，根本原因是终端未加载项目根目录node_modules/.bin路径；需检查terminal.integrated.defaultProfile配置、在项目级shell配置中添加export PATH="./node_modules/.bin:$PATH"，或统一使用npx turbo执行命令。

VSCode 里 turbo 命令报 command not found，不是没装 turbo，是终端根本没加载项目根目录下的 node_modules/.bin。

为什么 VSCode 终端找不到 turbo

VSCode 启动集成终端时，用的是系统 shell 的初始环境（比如 zsh 启动时读 ~/.zshrc），但不会自动把当前工作区的 ./node_modules/.bin 加进 PATH。尤其在 pnpm/yarn monorepo 中，turbo 只装在根 node_modules，而子包没有自己的 node_modules/.bin。

• 先运行 npx turbo --version —— 能输出版本号，说明 turbo 已安装，纯属路径缺失
• 检查 VSCode 设置里 terminal.integrated.defaultProfile 是否指向你日常用的 shell（macOS/Linux 是 zsh 或 bash；Windows 用户常误设成 PowerShell，导致 ~/.zshrc 不生效）
• 别改全局 PATH，直接在项目根目录的 .zshrc（或 .bashrc）末尾加：export PATH="./node_modules/.bin:$PATH"（注意是 ./，不是 $PWD/）
• 更稳妥的做法：所有命令都用 npx turbo，绕过 PATH 依赖

怎么在 VSCode 里一键运行 turbo run build

别硬写 turbo 命令，也别假设它全局可执行。VSCode 的 tasks.json 必须适配 monorepo 实际结构：工作目录、包范围、turbo 版本都得对齐。

• 在项目根目录建 .vscode/tasks.json，type 设为 "shell"，command 写 "npx turbo run build"
• group 设成 "build"，这样按 Ctrl+Shift+B（macOS 是 Cmd+Shift+B）就能唤出构建菜单
• 要只构建某个包（比如 packages/ui），加 --scope=ui 参数：npx turbo run build --scope=ui
• 别在 dependsOn 里写跨包依赖——turbo.json 的 pipeline 才管依赖拓扑，VSCode 任务只负责触发

turbo.json 缓存和 inputs/outputs 怎么配才不翻车

Turborepo 的缓存机制靠哈希比对输入文件内容来命中，配错 inputs 或 outputs 会导致缓存失效或误命，构建变慢甚至结果错误。

VSCode

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

下载

• inputs 必须包含所有影响任务输出的文件：源码、配置（tsconfig.json、package.json）、甚至 .env（如果构建逻辑读它）
• outputs 要精确到产物目录，比如 "dist/**" 或 "lib/**"，不能写太宽（如 "**"）否则缓存体积暴增
• 避免把 node_modules 放进 inputs —— 它本身由 lockfile 控制，turbo 会自动处理依赖变更
• 大型二进制产物（如 WASM、图标集）建议用 cacheDirectory 指向外部路径，或干脆关掉该任务缓存："cache": false

为什么 Ctrl+Click 跳转本地包失败

点 import { foo } from 'my-utils' 没反应，不是 VSCode 不行，是 TypeScript 语言服务不知道 my-utils 该去哪找源码。monorepo 里没有真实的 node_modules/my-utils 目录，只有 workspace 映射或 path alias。

• 确认根目录有 tsconfig.base.json，并在各包的 tsconfig.json 里用 "extends": "../tsconfig.base.json"
• 在 tsconfig.base.json 的 compilerOptions.paths 里配好映射，例如："my-utils": ["packages/my-utils/src"]（路径必须相对于 baseUrl）
• 改完 tsconfig 后，必须重启 TS Server：按 Cmd+Shift+P → 输入 Typescript: Restart TS server
• 如果用 pnpm workspace，确保 pnpm-workspace.yaml 正确声明了包范围，否则 pnpm link 不生效，TS 无法解析

最常被忽略的其实是 turbo.json 里 inputs 的粒度控制——少写一个 tsconfig.json，缓存就永远不命中；多写一个 node_modules，每次重装依赖都清空缓存。缓存不是开个开关就行，它得和你的实际构建逻辑严丝合缝。