vscode调试器报“cannot find runtime 'node'”的根本原因是其未继承shell环境变量，不识别nvm等版本管理工具的切换逻辑；需在launch.json中显式配置"runtimeexecutable"指向which node输出的真实路径。
node -v 在终端能跑，但 VSCode 调试器报 “Cannot find runtime 'node'”
这是老项目重构中最常卡住的第一步：命令行里 node -v 正常，F5 却直接失败。根本原因不是 Node 没装，而是 VS Code 的调试器没找到它——它不读你 shell 里的 nvm 切换逻辑，也不继承 GUI 启动时未加载的 ~/.zshrc。
实操建议：
用于自动切换项目中适合的node 版本
下载
根据 package.json 中的 engines 字段自动检测 Node.js 版本需求，未安装 nvm 时自动安装并切换至对应版本。支持 Windows、macOS、Linux。适用于 Node.js 项目开发、版本切换和环境配置。
- 先在系统终端执行
which node（macOS/Linux）或where node（Windows），拿到真实路径（比如/Users/xxx/.nvm/versions/node/v16.20.2/bin/node） - 打开项目根目录下的
.vscode/launch.json，在调试配置里显式写死路径："runtimeExecutable": "/Users/xxx/.nvm/versions/node/v16.20.2/bin/node" - 删掉
"runtimeExecutable"字段反而更危险——老项目往往用的是特定 Node 版本，自动查找会 fallback 到系统默认版本，导致fs.promises或fetch报错 - 如果用了
volta或fnm，别信“自动识别”，它们的 shim 机制对 VS Code 调试器是黑盒
package.json 里没写 "type": "module"，但代码用了 import/export
老项目常见混合写法：CommonJS 的 require() 和 ES Module 的 import 并存。Node.js 默认按 CommonJS 解析，遇到 import 就直接 SyntaxError: Cannot use import statement outside a module。
实操建议：
- 检查
package.json是否含"type": "module"；没有就加，但注意这会让所有.js文件强制走 ESM，require()会失效 - 若不能全局切 ESM，改用双后缀方案：
—index.cjs保留 CommonJS 入口
—utils.mjs用 ES Module 写新模块
—package.json中设"type": "commonjs"，靠后缀区分 - 调试时若用
ts-node或esbuild-node启动，launch.json必须配"runtimeArgs": ["--loader", "ts-node/esm"]，否则断点进不去
npm install 总卡在 node-gyp rebuild，尤其 Windows 上
老项目依赖里常含 sqlite3、bcrypt 等原生模块，Node 升级后 node-gyp 编译环境不匹配，npm install 卡死或报 MSBUILD : error MSB4025。
实操建议：
- 先确认当前 Node 版本是否支持该模块——查模块 npm 页面的
engines.node字段，比如bcrypt@5.1.0最高只支持到node >= 18.17.0 - Windows 用户必须装 Python 3.10（不是 3.11+）、Visual Studio Build Tools（非完整 VS），并运行：
npm config set python "C:\Python310\python.exe"npm config set msvs_version "2022" - 更省事的方案：用
npm install --no-optional跳过原生依赖，或换预编译版（如bcryptjs替代bcrypt） - 别用
cnpm—— 它的 symlink 机制和node-gyp冲突，错误信息比官方 registry 还难读
VSCode 里跳转不到 node_modules 里的函数定义
不是插件没装，也不是 TypeScript 配错了，而是老项目没声明 types 或用了非标准导出方式。比如 lodash 的 _.map 点不动，express 的 req.body 提示 any。
实操建议：
- 手动安装类型声明：
npm install -D @types/lodash @types/express @types/node - 检查
tsconfig.json是否含"types": ["node", "express"]，且"include"覆盖了.js文件（老项目常漏掉） - 若项目是纯 JS，确保根目录有
jsconfig.json，内容至少含：{"compilerOptions": {"allowJs": true, "checkJs": true}} - 禁用所有第三方 JS 补全插件（如 “JavaScript (ES6) code snippets”），它们会劫持跳转逻辑，和 VS Code 内置语言服务打架
process.env.NODE_ENV 的拼写错误被硬编码在 17 个文件里，改了就崩；又比如 node_modules 下某模块的 postinstall 脚本依赖旧版 npm 的生命周期行为。动手前，先 git clean -fdx 备份 node_modules，再逐个验证依赖的实际调用链。
