launch.json必须通过VSCode齿轮图标自动生成，不可手写；否则易遗漏env、cwd、preLaunchTask等关键字段，导致断点不触发、console.log不输出或“No configuration”报错，且configurations数组不能为空，每项须含type、request、name三字段，Node.js调试时program和console为必填。

launch.json 必须用齿轮图标生成，别手写

手动写 launch.json 极易漏掉关键字段，导致断点不触发、console.log 不输出、甚至整个调试面板报 “No configuration”。VS Code 的 ⚙️ 图标（在“运行和调试”面板右上角）会自动注入 env、cwd、preLaunchTask 等隐式依赖项，这些你手写时根本想不到。

常见错误：

• configurations 字段是空数组 [] 或直接删成 {} —— VS Code 会静默忽略，F5 按下后毫无反应
• 复制别人配置后只改了 program，却删掉了 type 和 request —— 这两个字段缺一不可，否则配置无效
• 文件放在 src/.vscode/launch.json 而不是项目根目录的 .vscode/launch.json —— VS Code 只认根目录下的版本

Node.js 调试必须填对 program 和 console

program 是入口文件路径，不是文件名也不是文件夹；console 决定日志是否可见——这两个字段在 type: "node" 时是硬性要求，不是可选。

正确写法：

• "program": "${workspaceFolder}/index.js" —— 推荐用变量，跨平台且协作安全
• "console": "integratedTerminal" —— 否则 console.log 会消失，断点悬停也可能失效

错误写法：

• "program": "index.js" 或 "./index.js" —— VS Code 不解析相对路径前缀，直接报 “Cannot find program”
• "console": "internalConsole" —— 日志被吞，输入阻塞，调试体验断裂
• TypeScript 项目写 "program": "${workspaceFolder}/src/index.ts" —— 不编译就跑，必然失败；要么配 preLaunchTask，要么改用 runtimeExecutable: "npx ts-node"

Express/Koa 类 Web 服务优先用 attach 模式

用 request: "launch" 启动 Express 很容易卡住：端口被占、环境变量不一致、子进程 fork 失败、EADDRINUSE 报错反复出现。attach 模式绕过启动环节，先手动跑起来再连，更贴近真实部署态。

Zenlink - Node SDK for ZenHeart

ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。

下载

实操步骤：

• 终端执行：node --inspect-brk ./bin/www（注意加 --inspect-brk 停在第一行）
• launch.json 中新增配置："type": "node"、"request": "attach"、"port": 9229
• 如果启动时用了 --inspect=9230，port 值必须同步改，否则连接超时
• Windows 下 cmd 有时连不上，换成 PowerShell，或显式写 --inspect=0.0.0.0:9229

别同时起两个 --inspect 进程——第二个会报 Could not connect to debug target，关掉所有 node 进程再试。

调试失败先查 node 是否可用，再查路径

VS Code 的 Node 调试器不是独立运行时，它只是调用你系统里的 node 命令。如果终端里 node -v 报错，所有配置都白搭。

排查顺序：

• Mac/Linux：运行 which node，若无输出，检查 nvm 是否加载（source ~/.nvm/nvm.sh），并确认 VS Code 是从该终端启动（code .）
• Windows：检查系统环境变量 PATH 是否含 C:\Program Files\nodejs\，安装时没勾 “Add to PATH” 就得手动加
• 改完 PATH 后必须重启 VS Code —— 它不会自动刷新环境变量
• program 路径必须指向真实存在的 JS 文件，不能是软链（如 node_modules/.bin/ts-node）、不能是文件夹、不能含未转义空格

真正容易被忽略的是：Node 版本低于 8.0 会导致断点灰掉、hover 看不到变量——因为旧版只支持已废弃的 --debug 协议，而 VS Code 调试器只认 --inspect。务必运行 node -v 确认 ≥ 8.0。