必须用根目录打开且各子包独立配置.nvmrc：根目录不放.nvmrc，每个子包（如packages/ui）单独放置并声明所需Node版本（如v18.12.1），配合terminal.integrated.inheritEnv和launch.json中runtimeExecutable指向子包node_modules/.bin/node确保版本精准生效。
必须用根目录打开，且每个子包有独立 .nvmrc
VSCode 本身不感知 Node 版本，它只依赖你启动时的 shell 环境和项目内声明的约束。Monorepo 中不同子包可能要求不同 Node 版本（比如前端用 v18.12.1，后端服务用 v20.9.0），所以不能只在根目录放一个 .nvmrc —— 那会强制所有子包共用同一版本，反而引发兼容问题。
正确做法是：
- 根目录不放
.nvmrc（除非所有子包真的一致） - 每个子包（如
packages/ui、apps/api）根目录下各自放一个.nvmrc，内容写明该包所需版本，例如：v18.12.1或lts/hydrogen - 确保
.gitignore中有!.nvmrc规则，但仅针对子包路径生效（如packages/**/.nvmrc不忽略）
VSCode 终端里 nvm use 不生效？检查 shell 初始化逻辑
即使子包里有 .nvmrc，VSCode 内置终端也可能不自动执行 nvm use——因为 VSCode 启动终端时没加载你的 shell 配置文件（如 ~/.zshrc），导致 nvm 命令根本不可用。
验证并修复方式：
- 在 VSCode 终端中运行
which nvm，如果返回空，说明 shell 没加载 nvm 初始化脚本 - 打开 VSCode 设置，搜
terminal.integrated.defaultProfile，确认选的是你日常用的 shell（如zsh，不是PowerShell或cmd） - 在对应 shell 的配置文件末尾添加：
export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" - 重启 VSCode（不是仅关闭终端），让新 shell 配置生效
launch.json 调试时 Node 版本错乱
VSCode 调试器默认用系统 PATH 中第一个 node，不会读 .nvmrc。如果你在 packages/backend 里调试，却用了 v16 的 node 执行 v20 语法的代码，就会报 SyntaxError: Unexpected token 'const' 这类错误。
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
解决方法是在 .vscode/launch.json 中显式指定 runtimeExecutable：
{
"configurations": [{
"type": "node",
"request": "launch",
"name": "Debug backend",
"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/node",
"program": "${workspaceFolder}/src/index.ts",
"cwd": "${workspaceFolder}",
"env": { "NODE_ENV": "development" }
}]
}
关键点：
-
runtimeExecutable指向子包自己的node_modules/.bin/node（前提是该包已安装node二进制 wrapper，比如通过pnpm add -D node-bin或类似工具） - 更稳妥的做法是：在子包
package.json的scripts中定义"debug": "node --inspect-brk src/index.ts"，然后在launch.json中用runtimeExecutable: "npm"+args: ["run", "debug"]
插件自动切换 Node 版本？别信“自动”，要验证实际进程
有些 VSCode 插件（如 Node.js Extension Pack 或 nvm for vscode）声称能“自动检测并切换 Node 版本”。但它们只是调用 nvm use 并修改终端环境变量，对调试器、任务（tasks.json）、甚至 ESLint 进程都不起作用。
真正可靠的判断标准只有一个：在调试或运行时，执行 process.version 或 console.log(process.versions)，看输出是否匹配你期望的版本号。不要只看状态栏显示或插件提示。
容易被忽略的点：
- VSCode 的“集成终端”和“调试器”是两个独立进程，各自维护一套环境变量
-
tasks.json中的命令（如pnpm build）默认继承终端环境，但如果任务配置了"presentation": { "echo": true }，可能绕过 shell 初始化逻辑 - CI 环境（GitHub Actions / GitLab CI）必须显式读取
.nvmrc，不能依赖 VSCode 插件
