launch.json 中 program 字段必须指向真实 js 文件，否则断点灰掉、f5 无反应；vscode 调试器只执行 node 可直接运行的 .js 文件，不解析路径或编译源码。
launch.json 里 program 字段必须指向真实 JS 文件
断点灰掉、F5 按下没反应，八成是 program 写错了。VSCode 调试器不会帮你解析路径或编译源码，它只认能被 node 直接执行的 .js 文件。
-
"program": "${file}"仅适合单文件快速测试，别用在后端项目里 - 后端项目务必写成
"program": "${workspaceFolder}/src/server.js"或"program": "${workspaceFolder}/app.js" - TypeScript 项目不能写
src/index.ts，得指向编译后的dist/index.js（前提是tsc已跑过且生成了.js.map） - ESM 项目需确保
package.json里有"type": "module"，否则import会解析失败
调试前必须验证 node 和 npm 在 VSCode 终端里可用
VSCode 调试器底层调用的是系统 node 命令，不是自带运行时。终端里 node -v 报错，调试必挂——这不是配置问题，是环境根本没到位。
Zenlink - Node SDK for ZenHeart
下载
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
- 打开 VSCode 内置终端（
Ctrl + `），直接执行node -v和npm -v，必须有输出 - macOS/Linux 用户：检查
~/.zshrc是否包含export PATH="/opt/homebrew/bin:$PATH"（Homebrew 安装路径），改完后source ~/.zshrc，再从该终端执行code .启动 VSCode - Windows 用户：重装 Node.js 时务必勾选
Add to PATH；若已装，手动把C:\Program Files\nodejs\加进系统环境变量Path，然后彻底退出 VSCode 再重开
npm start 或 nodemon 场景下不能直接改 program
想调试 npm start 或热重载服务？别把 program 改成 "npm" 或 "nodemon"，那样会导致调试断连、断点跳过甚至进程卡死。
- 调试
npm start：设"request": "launch"，"runtimeExecutable": "npm"，"runtimeArgs": ["start"]，并加"console": "integratedTerminal"看日志 - 调试
nodemon：放弃launch模式，改用attach——先在终端运行nodemon --inspect-brk src/server.js，再在launch.json中新增一个配置："type": "node"，"request": "attach"，"port": 9229 - 别在
runtimeArgs里手动加--inspect，VSCode 会自动注入，重复加导致端口冲突错误：address already in use
TS/ESM 项目容易漏掉的 source map 配置
断点停在 .js 文件里、变量 hover 不出来、调用栈显示 eval——不是代码问题，是源码映射链路断了。VSCode 不会自动读 tsconfig.json，必须在 launch.json 里显式声明。
- TypeScript：确认
tsconfig.json开启"sourceMap": true和"inlineSources": true，编译后.js.map和.js必须同目录 - 在
launch.json的配置里加"sourceMaps": true和"outFiles": ["./dist/**/*.js"] - 如果源码在子包里（如
packages/foo/src），还得加"resolveSourceMapLocations": ["${workspaceFolder}/packages/**/src/**", "!**/node_modules/**"] - ESM + TS 组合下，
runtimeExecutable推荐用"npx"+runtimeArgs: ["ts-node", "src/server.ts"]，而非硬指.js文件
