WebStorm调试Koa需填绝对路径、设正确工作目录、配置环境变量、在路由处理器而非app.listen()设断点，并确保中间件实际执行。
JavaScript file 必须填绝对路径，不能写 bin/www 或 app.js
WebStorm 的 Node.js 调试配置对入口文件路径极其严格：它不解析相对路径，也不展开 shell 语法。你填 ./bin/www 或 app.js，它会直接去当前工作目录下找同名文件——而实际项目中，bin/www 往往在子目录里，app.js 可能根本不在根目录。
- 右键点击项目中的真实入口文件（比如
bin/www或src/app.ts），选择 Copy Path → Copy Absolute Path，粘贴到JavaScript file栏 - 如果用 TypeScript，
JavaScript file必须指向编译后的dist/app.js，且tsconfig.json中sourceMap必须为true -
Working directory必须设为含package.json的项目根目录，否则require()可能因路径错乱加载失败
断点别打在 app.listen(3000) 上，优先设在中间件或路由 handler 里
Koa 是洋葱式中间件模型，app.listen() 只执行一次、不参与请求处理链，打在这行几乎永远停不住。
- 在具体路由处理器里设断点最可靠，例如：
router.get('/api/user', async (ctx) => { /* 在这行打点 */ ctx.body = ... }) - 避免在
async函数最外层打点后立刻return；V8 有时跳过帧信息，加一句console.log('debug')或临时赋值语句可稳定触发 - JPress 类项目（基于 Koa 的 CMS）建议优先在
routes/post.js或middleware/auth.js里设断点，比在server.js入口更早命中
调试时必须手动配置 PORT 和 NODE_ENV 环境变量
WebStorm 不会自动读取 shell 环境或 .env 文件。没配 PORT，服务可能监听默认 3000，但你本地端口已被占；没配 NODE_ENV=development，日志可能被静默、某些中间件（如错误堆栈、热重载）直接跳过。
- 在 Run/Debug Configuration 的
Environment variables栏里显式填入：PORT=3001;NODE_ENV=development - 若用 Docker 调试，确保容器内
PORT与 WebStorm 配置一致，且宿主机端口映射正确（如-p 3001:3001） - 检查
process.env.PORT是否真被读取：可在入口文件开头加console.log(process.env.PORT)验证
中间件执行顺序和 await next() 对断点命中的影响
断点是否能停住，不仅取决于位置，还取决于中间件是否真正执行到了那行。Koa 中间件链是“洋葱式”，await next() 是控制流分水岭——前面的代码总能执行，后面的代码只在 next() 返回后才执行。
- 如果你在中间件 A 里打了断点，但中间件 B 抛出错误且没被
errorMiddleware捕获，A 的后续代码（await next()之后）就不会运行，断点也就不会触发 - 想确认中间件是否被调用，可在其开头加
console.log('in auth middleware')；比依赖断点更直观 - 调试嵌套异步逻辑时，注意 V8 的 async stack trace 有时不完整，配合
console.trace()查看调用栈更稳妥
实际调试时，最容易被忽略的是环境变量缺失导致的“服务启动成功但请求无响应”，以及断点设在非执行路径上造成的“明明打了点却从不停”。这两点没有报错提示，纯靠经验排查。
