VSCode调试Node.js必须满足三个前提：一是在内置终端（Ctrl+`）中能执行node -v和npm -v；二是launch.json需显式配置"type": "node"、"runtimeExecutable"（nvm/fnm路径）和"env"（手动加载环境变量）；三是TypeScript项目须在launch.json中启用"sourceMaps": true并正确设置"outFiles"和"resolveSourceMapLocations"。

node 命令必须在 VSCode 内置终端里能直接执行，否则所有调试配置都无效——这是最常被跳过的前提。

先确认 node 和 npm 在终端可用

别只在系统终端里验证，必须在 VSCode 自带的终端（Ctrl + `）里运行：node -v 和 npm -v。如果报错“command not found”，说明 VSCode 没读到你改好的 PATH。

• Windows 用户重点检查安装路径：避开 C:\Program Files\nodejs 这类含空格或中文的路径
• macOS/Linux 用户常见问题是 shell 启动 VSCode 时没继承 PATH，比如用 zsh 安装了 node，但 VSCode 是从 Dock 启动的——它根本不知道 which node 输出的路径
• 改完环境变量后，必须完全退出 VSCode（不是关窗口，是 Quit），再重新打开

launch.json 必须显式写对这三项

VSCode 自动生成的模板经常漏掉关键字段，导致断点不触发、process.env 为空、日志看不到输出。

Rydberg Agent Node

使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r

下载

• "type": "node"：别手写 "pwa-node"，尤其老项目或 CI 场景下 fallback 不稳定
• "runtimeExecutable"：当你用 nvm 或 fnm 切换版本时，必须填绝对路径，比如 /Users/you/.nvm/versions/node/v20.15.0/bin/node；不写就按 PATH 找，而 PATH 里的 node 可能和终端里看到的不是同一个
• "env"：.env 文件不会自动加载，开发环境变量如 NODE_ENV、PORT 必须手动写进配置，例如："env": {"NODE_ENV": "development", "PORT": "3001"}

调试 Express/Koa 等 Web 服务时，别让断点卡在启动前

默认 request: "launch" 模式会在入口文件第一行就暂停，但 Web 服务真正执行路由逻辑是在 app.listen() 之后——你打的断点根本没机会命中。

• 正确做法是加 "args": ["--inspect-brk"]，让 Node 启动即中断，等 VSCode 附加后再继续执行
• 如果用了 nodemon，不要直接替换 runtimeExecutable 为 nodemon；要配成："runtimeExecutable": "${workspaceFolder}/node_modules/.bin/nodemon"，并加 "runtimeArgs": ["--inspect-brk", "${workspaceFolder}/app.js"]
• 避免用 spawn() 启动子进程——它不自动暴露调试端口；改用 fork() 并传 execArgv: ['--inspect=9230']，否则 autoAttachChildProcesses: true 也抓不到

TypeScript 项目里断点停在 .js 文件？源码映射链断了

VSCode 不会读 tsconfig.json 里的 "sourceMap": true，必须在 launch.json 里双重声明。

• 编译时确保生成 .map 文件：tsc --sourceMap 或 tsconfig.json 中设 "sourceMap": true
• launch.json 里加："sourceMaps": true 和 "outFiles": ["./dist/**/*.js"]（路径要和实际输出目录一致）
• 如果 .ts 文件不在根目录下（比如在 packages/foo/src），还得加 "resolveSourceMapLocations" 显式放行：["${workspaceFolder}/packages/**/src/**", "!**/node_modules/**"]

真正容易被忽略的是：autoAttachChildProcesses: true 这个开关只对 child_process.fork() 和 Worker 生效，且 Worker 必须自己带 --inspect-brk 参数，否则 VSCode 根本不知道它存在。