断点不生效主因是 node 未加入 VSCode 调试器 PATH 或 launch.json 中 program 路径错误；需确保 shell 配置正确加载、program 指向真实存在的编译后 JS 文件，并验证 sourceMap 配置完整。
断点不生效，八成是 node 没进 VSCode 调试器的 PATH，或者 program 指向了错误路径——这两处不对，其他配置再细也没用。
VSCode 里 node -v 有输出，但调试报 “Cannot find runtime 'node' on PATH”
这不是插件问题，是 VSCode 启动时没加载你的 shell 配置（比如 ~/.zshrc），导致调试器根本看不到 node。
- macOS/Linux：检查
~/.zshrc是否包含export PATH="/opt/homebrew/bin:$PATH"（Homebrew 安装路径）或类似语句；没有就加上，然后运行source ~/.zshrc - Windows：重装 Node.js，务必勾选 “Add to PATH”；或手动把
C:\Program Files\nodejs\加进系统环境变量 - 验证方式：在 VSCode 内置终端（
Ctrl + `）里执行node -v和which node，两者都必须有输出 - 改完后必须彻底退出 VSCode 所有进程（包括托盘图标），再从终端启动：
code .
launch.json 中 program 字段写错，断点全灰点不进去
program 必须是相对于工作区根目录、真实存在的可执行 JS 文件路径，不是源码，也不是命令行写法。
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
用 npm start 启动的服务，断点完全不触发
因为 npm start 默认不加 --inspect-brk，Node 进程没暴露调试端口，VSCode 连都连不上。
- ✅ 推荐做法：在
launch.json中用"request": "launch"，"program"直接指向入口 JS 文件（如bin/www），让 VSCode 自己带参数启动 - ❌ 别手动终端跑
npm start，再切回 VSCode 选 “Attach to Process”——除非package.json的 script 显式写了--inspect-brk -
--inspect-brk会让进程停在第一行，适合设启动断点；--inspect不暂停，只用于attach场景 - Express/Koa 服务卡住或报
EADDRINUSE？优先改用"request": "attach"模式：先终端跑node --inspect-brk ./bin/www，再配"port": 9229
TypeScript 断点停在 .js 文件里，或显示空心红圈
说明 source map 链路断了，VSCode 找不到原始 .ts 和编译后 .js 的映射关系。
- 确认
tsconfig.json开了"sourceMap": true，且构建后生成了.js.map文件 -
launch.json中必须加"sourceMaps": true和"outFiles": ["./dist/**/*.js"]（路径按实际输出目录调整） - 如果
.ts在子包里（如packages/foo/src），还要加"resolveSourceMapLocations"显式放行：["${workspaceFolder}/packages/**/src/**", "!**/node_modules/**"] - 改完配置后必须重启调试会话，不能只刷新页面
最容易被忽略的是：VSCode 调试器和终端用的是两套环境变量，哪怕你在终端里 node -v 正常，调试器也可能完全找不到 node；另一个隐形坑是 program 路径看似合理，但只要没生成对应 JS 文件或路径拼错一个字符，断点就永远是空心圆。
