VSCode下Corepack锁定Node项目NPM/PNPM版本

先说几个核心判断。VSCode 里“pnpm 命令找不到”这类问题，十有八九不是 VSCode 本身出了毛病，而是它内置终端没加载 shell 初始化文件，导致 PATH 环境变量里缺了 Corepack 生成的 shim 路径。这事儿看着小，但卡起人来真是一卡一个准。

VSCode 终端里 pnpm 命令找不到，但 package.json 写了 packageManager

这个问题出现的频率相当高，而且很容易被误判成“VSCode 没配置好”。实际原因说出来其实很直接：VSCode 内置终端在启动时，压根儿不加载你的 shell 初始化文件（比如 ~/.zshrc），所以 PATH 变量里自然就没有 Corepack 生成的 shim 路径。

怎么验证？很简单，先在你的系统终端（不是 VSCode 里面）跑一下 which pnpm。如果没输出，说明 Corepack 的 shim 根本就没进 PATH；如果有输出，比如 /Users/xxx/.nvm/versions/node/v22.21.0/lib/node_modules/corepack/shims/pnpm，那问题就明确了——VSCode 终端没继承这个 PATH。

解决方式分平台：

• macOS / Linux：确认 ~/.zshrc 末尾有 export PATH="$HOME/.nvm/versions/node/v22.21.0/lib/node_modules/corepack/shims:$PATH"，具体路径以 which corepack 的输出为准。
• Windows PowerShell：在 $PROFILE 里加上 Set-Alias -Name pnpm -Value "$env:LOCALAPPDATA/corepack/shims/pnpm.ps1"，并且确保已经执行过 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。

这里有个关键动作：改完之后，必须重启 VSCode，而不是仅仅关闭终端窗口。否则，你用 code . 启动时，环境还是旧的。

tasks.json 里写 "npm install" 却想跑 pnpm，结果报 command not found

VSCode 的任务系统是个很实在的玩意儿——它不认 alias，不读 profile，不搞 shell 解析那一套。它就是字面匹配 PATH 里的可执行文件名。你写 "command": "npm"，它就老老实实去找 npm，哪怕你在终端里 alias 了 npm=pnpm，它也完全无视。

正确做法只有一条：显式替换。

• 把 "command": "npm" 改成 "command": "pnpm" 或者 "command": "corepack"。
• 如果用 corepack，args 得写成 ["pnpm", "install"]，不能只写 ["install"]。
• 确保项目根目录下的 package.json 里，packageManager 字段存在且格式正确。比如 "pnpm@9.15.0"，不能是 "pnpm@^9" 或 "pnpm@latest"。
• CI/CD 中同理：别依赖 npm install 自动 fallback，直接写 corepack pnpm install 最靠谱。

TS Server 跳转失败、import 报红但运行正常

这个问题跟 Corepack 其实没关系，根子在于 TypeScript 语言服务没识别到 pnpm 的链接结构。Node.js 运行时能 resolve 成功，是因为 pnpm 自己 patch 了 resolver，但 TS Server 只看 node_modules 和 tsconfig.json 里的 paths，它不会主动去扫描 .pnpm 那个硬链接目录。

要让 TS Server 正常工作，必须满足三个条件：

• VSCode 工作区打开的是整个 monorepo 的根目录（必须包含 pnpm-workspace.yaml 和 pnpm-lock.yaml），不能只开某个 packages/foo 子目录。
• tsconfig.json 里要启用 "composite": true，并且在 "references" 中声明 workspace 内的其他包。
• 最后，手动重启 TS Server。按 Ctrl+Shift+P，输入 Typescript: Restart TS server，别指望保存 tsconfig 就能自动生效。

切换 Node 版本后 pnpm 版本错乱或 corepack 失效

用 nvm 或 n 切换 Node 版本后，Corepack 的 shim 路径可能会失效——因为新 Node 版本下的 corepack 二进制位置变了，旧的 shim 指向的路径已经不存在了。

这不是 bug，而是设计如此。每次切换 Node 主版本（比如从 v18 切到 v22），都必须重新启用 Corepack：

• 运行 corepack enable（注意空格，不是 corepackenable）。
• 进入项目目录后，手动触发一次 corepack use pnpm@9.15.0，强制重写 shim。
• 检查 pnpm --version 是否输出你预期的版本。如果还是旧版，说明 packageManager 字段被忽略了，大概率是 package.json 语法错误或者 JSON 校验失败。

还有一个最容易忽略的细节：Corepack 只读取项目根目录下的 package.json。如果你在子目录里打开 VSCode，它根本看不到那个 packageManager 字段，自然也就不会生效。