VSCode调试Node.js断点失效主因是launch.json配置错误或node未被正确识别；需验证PATH、program路径（如"${workspaceFolder}/dist/index.js"）、sourceMaps、attach端口及type为小写"node"。
VSCode 本身不“配置 Node.js 环境”，它只是调用你系统已安装的 node 和 npm；所谓“最佳配置”本质是让 VSCode 正确识别、稳定调用、高效调试你本地的 Node.js 运行时——关键在路径、版本、终端继承和调试器联动这四点。
确认 node 和 npm 已全局可用
VSCode 的集成终端（Terminal）默认继承系统 PATH，但 Windows 用户常因安装方式（如使用 nvm-windows 或 Scoop）导致终端能运行 node -v，而调试器却报 Command "node" not found。这不是 VSCode 配置问题，而是 PATH 没被 GUI 进程加载。
- macOS / Linux：检查
~/.zshrc或~/.bash_profile中是否导出PATH，并确保 VSCode 是从终端启动（code .），而非桌面图标 - Windows：避免用“Node.js Installer”默认安装到
C:\Program Files\nodejs\后又手动删掉；推荐用nvm-windows管理多版本，并执行nvm use 20.15.0后再启动 VSCode - 验证方式：在 VSCode 终端中运行
which node（macOS/Linux）或where node（Windows），再打开一个新调试会话，看Debug Console是否能执行process.version
launch.json 中 runtimeExecutable 什么情况下必须显式指定？
仅当你要：① 调试非默认版本（比如项目要求 Node.js 18，但系统默认是 20）；② 使用自定义构建的 node（如 Electron 内置 runtime）；③ 在容器或 WSL 中调试但主机 PATH 不一致。
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
- 显式指定示例：
{ "configurations": [{ "type": "node", "request": "launch", "name": "Launch with Node 18", "runtimeExecutable": "/Users/you/.nvm/versions/node/v18.19.1/bin/node", "program": "${workspaceFolder}/index.js" }] } - 不要为“统一版本”而硬编码路径——这会让团队协作失效；改用
nvm+ 终端启动才是可持续方案 -
runtimeVersion字段（VSCode 1.85+）可声明期望版本，但不会自动切换，仅用于提示不匹配时告警
为什么 npm install 成功，但 require() 报 Cannot find module？
这不是 Node.js 环境配置失败，而是 VSCode 的 JavaScript/TypeScript 语言服务未识别 node_modules 结构，常见于：单仓库多包（monorepo）、软链接依赖（npm link）、或 package.json 缺少 "type": "module" 导致 CJS/ESM 混用。
- 先运行
npm ls <module-name>确认模块真实存在且无extraneous标记 - 检查当前文件扩展名：.js 默认为 CommonJS，.mjs 或含
"type": "module"才启用 ESM；混用时import不能 require.js，反之亦然 - VSCode 中按
Cmd+Shift+P→Developer: Restart TS Server可刷新模块解析缓存 - 若用 pnpm，确保已启用
"pnpm.enableWorkspaceDetection": true（VSCode 设置）
调试时断点不命中？重点查这三项
断点失效绝大多数与 sourcemap 或入口路径偏差有关，和 Node.js 版本关系不大。
- 确保启动配置中
"sourceMaps": true（TypeScript 项目必须），且编译输出含.map文件；tsc --build默认生成，但ts-node需加-r ts-node/register/transpile-only并配tsconfig.json的sourceMap -
"outFiles"路径需匹配实际生成位置，例如"outFiles": ["${workspaceFolder}/dist/**/*.js"]，别写成./build却生成到./dist - 检查
program字段是否指向编译后文件（如dist/index.js），而不是源码（src/index.ts）——后者会导致调试器找不到映射
最易被忽略的是：VSCode 的 Node.js 调试器不会自动 reload launch.json 修改，每次改完必须重启调试会话；而终端里的 node 版本、package.json 的 engines 字段、以及 .nvmrc 文件三者之间的一致性，比任何 VSCode 设置都关键。
