先确认node是否真在vscode环境里：调试器不继承shell环境变量，需在settings.json中显式注入path；program必须为绝对路径如"${workspacefolder}/dist/index.js"；ts项目须配sourcemaps、outfiles及resolvesourcemaplocations。
断点不生效？先看 node 是否真在 VSCode 环境里
VSCode 调试器报 Cannot find runtime 'node' on PATH，或者断点全灰点不了，八成不是配置问题，而是它根本没加载你的 shell 环境变量。你在终端里能跑 node -v，不代表调试器也能——尤其 macOS/Linux 下用图形界面启动 VSCode 时，~/.zshrc 或 ~/.bash_profile 常被跳过。
- 在 VSCode 内置终端（
Ctrl + `）执行which node，拿到真实路径（如/opt/homebrew/bin/node） - 在
.vscode/settings.json里显式注入 PATH："terminal.integrated.env.osx": { "PATH": "/opt/homebrew/bin:${env:PATH}" } - 改完必须彻底退出 VSCode 所有进程（macOS 上 Activity Monitor 杀掉所有 Code 进程），再从终端运行
code .启动 - Node 版本不能低于 14，否则 async_hooks 支持不全，断点可能挂不住异步栈
launch.json 的 program 字段写错，断点永远进不去
program 不是命令行参数，也不是相对路径语法，它是调试器启动时要执行的 JS 文件的**绝对路径（相对于工作区根目录）**。写错一个字符，VSCode 就静默失败，连错误提示都不给。
Rydberg Agent Node
下载
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
- 正确写法：
"program": "${workspaceFolder}/dist/index.js"（推荐用变量，避免硬编码） - 错误写法：
"program": "src/index.js"（缺${workspaceFolder}/，VSCode 找不到） - 错误写法：
"program": "./src/index.js"（.在这里不解析，等同字面量） - TypeScript 项目别写
src/index.ts；要么编译后指向dist/index.js，要么配preLaunchTask触发tsc - ESM 项目必须在
package.json里加"type": "module"，否则import解析失败，直接报Cannot find module
TS 断点停在 .js 里？sourceMap 链路断了
VSCode 不会自动读 tsconfig.json 的 sourceMap: true，必须在 launch.json 里双重确认映射是否可达。断点停在 dist/index.js 里而不是 src/index.ts，就是典型映射失败。
- 确保编译生成了
.map文件：tsc --sourceMap或tsconfig.json中设"sourceMap": true -
launch.json必须同时启用："sourceMaps": true和"outFiles": ["./dist/**/*.js"] - 如果
.ts文件不在根目录（比如packages/foo/src），还得加"resolveSourceMapLocations": ["${workspaceFolder}/packages/**/src/**", "!**/node_modules/**"] - 不配
outFiles，VSCode 就不知道该把dist/index.js的哪一行映射回src/index.ts—— 断点只能停在 JS 上
Attach 模式才是 Express/Koa 服务的稳妥调试方式
用 request: "launch" 硬启服务，容易和环境变量、子进程、端口监听冲突，一调试就卡住或报 EADDRINUSE。生产级调试几乎都走 attach 模式。
- 先在终端手动跑：
node --inspect-brk ./dist/index.js（停在第一行，留出连接窗口） -
launch.json关键项："type": "node"、"request": "attach"、"port": 9229 - 如果用了自定义端口，比如
--inspect=9230，port值必须同步改，否则连不上 - 别同时起两个
--inspect进程——第二个会报Starting inspector on 127.0.0.1:9229 failed: address already in use - Docker 内调试需设
"address": "0.0.0.0"并暴露端口，"localhost"在容器里不通
