VSCode调试Node.js失败的根源在于环境链路、调试路径和多进程联动三处配置缺失；需确保GUI启动时PATH正确继承、launch.json中program指向编译后.js文件且sourceMap配置匹配、Worker或子进程启用autoAttachChildProcesses并统一--inspect端口。
VSCode 本身不“配置 Node.js 环境”，它只调用你系统已装的 node 和 npm；所谓“额外配置”，本质是让 VSCode 正确继承、稳定调用、精准调试——关键在环境链路、调试路径、多进程联动这三处。
为什么终端能跑 node -v，但调试器报 Command "node" not found？
这不是插件问题，而是 GUI 启动的 VSCode 没加载你的 shell 初始化文件（如 ~/.zshrc），导致 PATH 缺失 Node 路径。
- macOS/Linux：确认
~/.zshrc中有source ~/.nvm/nvm.sh和nvm use --delete-prefix v18.19.0（或对应版本），且 VSCode 是从终端启动：code . - Windows：用
nvm-windows时，必须先运行nvm use 20.15.0，再启动 VSCode；若用 Scoop 安装，确保scoop shim已生成 - 验证方式：在 VSCode 终端里执行
where node（Windows）或which node（macOS/Linux），输出路径应与调试器一致 - 临时补救：在项目根目录的
.vscode/settings.json中写入{"terminal.integrated.env.osx": {"PATH":"/opt/homebrew/bin:${env:PATH}"}}，改完必须彻底重启 VSCode
launch.json 中 program 字段填错，断点永远不生效
program 必须指向编译后的真实 .js 文件，不是 .ts、.mjs，也不是 npm start 这类脚本。
Rydberg Agent Node
下载
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
- TypeScript 项目：设
"program": "${workspaceFolder}/dist/index.js"，并确保tsconfig.json中"sourceMap": true且未启用"inlineSourceMap": true - ESM 项目（含
"type": "module"）：仍填.js路径，但加"runtimeArgs": ["--experimental-specifier-resolution=node"] - 避免写
"runtimeExecutable": "npm"——npm不是node，调试器无法注入断点 - 常见错误：断点打在
src/index.ts上，但program指向src/index.ts，调试器直接报 “Cannot launch program”
调试 Worker Threads 或 fork 子进程，光开多个终端没用
开两个终端分别跑 node main.js 和 node worker.js，只是两个孤立进程；真要跨上下文调试，必须启用子进程自动附加。
- 在
launch.json配置中必须加"autoAttachChildProcesses": true - Worker 构造函数需显式传参：
new Worker('./worker.js', { execArgv: ['--inspect-brk=9229'] }) - 主进程也要配
"runtimeArgs": ["--inspect-brk"]和"port": 9229，端口必须一致且未被占用 -
child_process.fork()同样需要execArgv，否则子进程根本不开调试端口 - 注意：
autoAttachChildProcesses对spawn()无效，除非手动加--inspect参数
真正卡住人的，往往不是不会配，而是不知道哪一环断了——比如 node 路径在终端和调试器里不一致，或者 sourceMap 生成了但没告诉调试器去哪找，又或者 Worker 启动时压根没带 --inspect-brk。这些地方不细看日志、不验证路径、不比对版本，很容易反复折腾却原地打转。
