VSCode调试Node.js报“Cannot find runtime 'node'”是因未加载shell配置导致PATH缺失，需修正环境变量并重启VSCode；launch.json中program必须用${workspaceFolder}变量指向真实JS文件；TS调试需启用sourceMap、sourceMaps及正确outFiles和resolveSourceMapLocations；Web服务推荐attach模式并确保--inspect参数一致。
node命令在终端可用，但调试器报“Cannot find runtime 'node' on PATH”
这不是 VSCode 插件坏了，是它启动时压根没加载你的 shell 初始化文件（比如 ~/.zshrc 或 ~/.bash_profile），所以 PATH 里没有 node。
macOS/Linux 用户检查：~/.zshrc 是否有类似 export PATH="/opt/homebrew/bin:$PATH" 的行（Homebrew 安装路径）；没有就加上，然后运行 source ~/.zshrc，再彻底退出 VSCode 所有进程，从终端执行 code . 启动。
Windows 用户重装 Node.js，务必勾选 “Add to PATH”；或手动把 C:\Program Files\nodejs\ 加进系统环境变量的 Path。
验证方式：在 VSCode 内置终端（Ctrl + `）里执行 node -v，必须有输出；如果终端里有、调试器里报错，说明调试器根本没读到这个 PATH。
launch.json 中 program 字段总报错或断点不生效
program 必须指向一个真实存在的、可执行的 JS 文件（如 index.js），且路径是相对于工作区根目录的绝对路径表达式，不是相对路径语法，也不是命令行参数。
- ✅ 正确写法：
"program": "${workspaceFolder}/dist/index.js"（推荐用变量，跨平台、协作安全） - ❌ 错误写法：
"program": "src/index.js"（缺${workspaceFolder}/，VSCode 找不到） - ❌ 错误写法：
"program": "./src/index.js"（.在这里不被解析，等同字面量） - ❌ 错误写法：
"program": "C:/project/src/index.js"（换机器就失效，团队协作时直接被拒） - ❌ 错误写法：
"program": "node_modules/.bin/ts-node"（指向软链或可执行脚本，VSCode 报 “not a valid program”）
TypeScript 项目想直接调试 .ts？可以，但得配 runtimeExecutable："runtimeExecutable": "npx ts-node"，否则报 Cannot launch program because corresponding JavaScript cannot be found。
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
断点停在 .js 上，而不是你写的 .ts 源码
这不是 bug，是 source map 链路断了——调试器只能看到编译后的产物，没法映射回原始 TS 行号。
必须同时满足三项：
-
tsconfig.json中"sourceMap": true（且别开"inlineSourceMap": true，VSCode 更认独立.map文件） -
launch.json中"sourceMaps": true -
"outFiles": ["${workspaceFolder}/dist/**/*.js"]（路径要和你构建输出一致） -
"resolveSourceMapLocations": ["${workspaceFolder}/src/**", "!**/node_modules/**"]（告诉调试器去哪里找原始源码）
打开「调试控制台」搜 Loaded source map from:：看到 404 就代表路径错；看到成功加载但行号仍错位，大概率是构建时用了 inlineSourceMap 却没关掉。
Web 服务类应用（Express/Koa/Nest）调试卡死或连不上
对这类应用，request: "launch" 往往卡在端口占用、子进程 fork、环境变量不一致上；request: "attach" 是更稳的选择——你先手动跑起来，VSCode 再连上去。
操作步骤：
- 先在终端执行：
node --inspect-brk ./bin/www（注意加--inspect-brk让它停在第一行） -
launch.json关键项："type": "node"、"request": "attach"、"port": 9229（若启动时用了--inspect=9230，这里必须同步改） - Windows 下用
cmd启动有时连不上，换成 PowerShell，或显式加--inspect=0.0.0.0:9229 - 别同时起两个
--inspect进程，端口冲突会导致第二个报Could not connect to debug target
真正容易被忽略的是：改完环境变量后必须重启 VSCode —— 它不会自动刷新 PATH；还有就是 skipFiles 默认跳过 node_modules，真要调试依赖源码，得删掉或重置它。
