先确认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" 在容器里不通

复杂点往往藏在环境变量继承和 sourceMap 路径映射这两层，而不是 launch.json 表面字段。调试器连不上、断点不命中，90% 是这两处出了偏差。