launch.json 的 program 必须指向已编译的 js 文件（如 "${workspacefolder}/dist/index.js"），而非 ts 源码或目录；typescript 项目需配置 sourcemap、outdir，并确保 .map 文件存在且路径匹配，否则断点失效。
launch.json 的 program 必须指向可执行的 JS 文件，不是 TS 或入口目录
断点灰掉、调试器启动后直接退出，90% 是因为 program 指向了 src/index.ts 或 ./src 这类非运行时文件。VSCode 的 Node 调试器不编译、不转译，它只调用 node 命令去执行一个真实存在的 .js 文件。
-
program正确写法："${workspaceFolder}/dist/index.js"（前提是 TypeScript 已编译输出） - 错误写法：
"src/index.ts"（node无法直接执行）、"./src"（不是文件）、"src/index.js"（缺${workspaceFolder}/，路径解析失败） - TypeScript 项目必须配
tsconfig.json：确保"sourceMap": true、"outDir": "dist"，且dist/下真有index.js和同名.map文件
SourceMap 映射失效？重点查 outFiles 和 resolveSourceMapLocations
sourceMaps: true 只是开关，真正决定“JS 映射回哪段源码”的是 outFiles 和 resolveSourceMapLocations。填错一个路径通配符，断点就永远停不住。
-
outFiles必须精确匹配编译产物路径，例如：["${workspaceFolder}/dist/**/*.js"]；若输出到dist/cjs/和dist/es/，就得写成["${workspaceFolder}/dist/cjs/**/*.js", "${workspaceFolder}/dist/es/**/*.js"] -
resolveSourceMapLocations控制 VSCode 去哪找源码，常见写法：["${workspaceFolder}/**", "!**/node_modules/**"]；如果项目用了路径别名（如@/utils），需额外加映射规则，比如"webpack:///src/*": "${workspaceFolder}/src/*" - 检查生成的
dist/index.js末尾是否有且仅有一行：//# sourceMappingURL=index.js.map，且index.js.map文件真实存在于同一目录
用 nodemon 热重载调试时，runtimeExecutable 不能直接写 "nodemon"
直接设 "runtimeExecutable": "nodemon" 会导致 VSCode 启动失败或断点断连——它找不到全局命令，或无法传递 --inspect-brk 参数。
Rydberg Agent Node
下载
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
- 推荐写法：
"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/nodemon"（Linux/macOS）或"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/nodemon.cmd"（Windows） -
runtimeArgs必须显式带上调试参数：["--inspect-brk", "${workspaceFolder}/dist/index.js"]；漏掉--inspect-brk就不会暂停在第一行，断点可能错过初始化逻辑 - 避免和
package.json中的npm run dev冲突：确保nodemon版本 ≥ 3.0.0，旧版对--inspect支持不稳定
性能敏感场景下，skipFiles 和 trace 配置影响调试响应速度
大型项目里，调试器默认会尝试加载所有模块的 source map，包括 node_modules 里的依赖，这会导致首次断点命中慢 2–5 秒，甚至卡死。
- 强制跳过内部代码：
"skipFiles": ["<node_internals>/**", "**/node_modules/**"]</node_internals>（注意双星号匹配子目录） - 启用调试日志定位瓶颈：
"trace": true会在 Debug Console 输出协议通信细节，但仅用于排查卡顿，上线前务必关掉 - ESM 项目额外注意：
package.json中必须有"type": "module"，否则import解析失败，source map 无法关联原始路径
真正卡住的地方往往不是配置项本身，而是 .map 文件里 sources 字段写的路径和 resolveSourceMapLocations 对不上——比如 map 里写的是 webpack:///./src/index.ts，但你的 webRoot 设成了 "${workspaceFolder}"，少一个 / 就映射失败。
