koa 在 vscode 中调试成功的两个核心前提是：node 命令在集成终端中可用，且 launch.json 的 program 字段必须指向真实可执行的 .js 文件；其余配置均围绕这两点展开验证与修复。
直接说结论：Koa 本身不依赖特殊配置，VSCode 跑 Koa 的核心障碍只有两个——node 命令在 VSCode 终端里能跑通，且 launch.json 的 program 指向的是真实可执行的 .js 文件。其余都是围绕这两点展开的补救或优化。
确认 node 命令在 VSCode 集成终端中可用
这是最常被忽略的第一步。VSCode 启动时不一定继承你 shell 的 PATH，尤其 macOS/Linux 下用 zsh 或 fish 启动 VSCode 时容易丢掉 node 路径。
- 在 VSCode 内置终端（
Ctrl + `）里直接运行node -v，失败就说明环境没接上 - 运行
which node（macOS/Linux）或where node（Windows），记下输出路径，比如/opt/homebrew/bin/node - 在项目根目录下创建或编辑
.vscode/settings.json，显式补全 PATH：{ "terminal.integrated.env.osx": { "PATH": "/opt/homebrew/bin:${env:PATH}" } }（Windows/Linux 对应改env.windows或env.linux） - 改完必须重启 VSCode，环境变量不会热更新
launch.json 的 program 必须指向 .js 文件，不能是 .ts 或入口别名
VSCode 的 Node 调试器只认编译后能被 node 直接执行的文件。写错路径、指向源码或未编译文件，断点必然失效。
Rydberg Agent Node
下载
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
- 如果你用 TypeScript，
program必须填编译后的路径，例如"${workspaceFolder}/dist/server.js"，而不是"${workspaceFolder}/src/server.ts" - 确保
tsconfig.json中启用了"sourceMap": true和"outDir": "./dist" - 如果用 ESM（
package.json里有"type": "module"），入口文件可以是.mjs，但 Node 版本需 ≥ 18.17；不要手动加--loader参数 - Koa 脚手架（如
koa2 myapp）默认入口是bin/www，不是index.js，program必须同步改成"${workspaceFolder}/bin/www"
用 nodemon 热重载时，别让 launch.json 直接调用 nodemon
把 runtimeExecutable 设成 "nodemon" 或硬编码路径，在不同系统上极易报 spawn nodemon ENOENT；更糟的是，VSCode 无法 attach 到 nodemon 启动的子进程，断点会丢失。
- 推荐用
attach模式：先在终端运行npm run debug（脚本内容为nodemon --inspect-brk ./src/server.js） - 等终端输出
Debugger listening on ws://127.0.0.1:9229/后，再在 VSCode 里选attach类型的调试配置 - 对应
launch.json配置：{ "type": "node", "request": "attach", "name": "Attach to nodemon", "port": 9229, "address": "localhost", "restart": true, "sourceMaps": true, "skipFiles": ["<node_internals>/**"] }</node_internals> - 这样既热重载，又保断点，且跨平台稳定
断点不触发？先验证请求是否真进到你的代码
90% 的“断点不生效”其实是请求根本没走到那行——中间件提前 return、body 解析失败、路由没匹配、代理转发错误，都可能导致断点形同虚设。
- 在第一个中间件里加
console.log('hit')或打个断点，看请求进来时有没有触发 - 用
curl -v http://localhost:3000/your-route或 Postman 发请求，观察终端日志是否出现预期输出 - 检查 Koa 中间件顺序：比如
app.use(koaBody())如果 body 太大或格式错，后续所有路由都不会执行 - 确认开发端口没冲突：Koa 默认监听
3000，但若代码里读取了process.env.PORT，而你没设该变量，可能实际监听undefined端口
真正麻烦的从来不是装几个包，而是 node 找不见、program 指错了、nodemon 和调试器没对上频道——这些地方一错，整个调试链就断了，而且错误表现还五花八门。动手前先盯住这两个点：终端里 node -v 有输出吗？launch.json 里的 program 路径打开看看是不是真存在、能不能被 node 直接执行？
