webstorm调试koa/jpress需用绝对路径配置入口文件、在中间件或路由处理器设断点、显式设置环境变量、docker调试时正确映射端口并确保源码路径一致。
入口文件路径必须填绝对路径，不能写 ./bin/www 或 index.js
WebStorm 的 Node.js 调试配置对 JavaScript file 字段极其严格：它不解析相对路径，也不执行 shell 式的命令行展开。你填 ./bin/www 或 index.js，它会直接尝试加载当前工作目录下的同名文件——但多数 Koa/JPress 项目入口实际在 bin/www（Express 风格）或 app.js（Koa 常见），而 WebStorm 工作目录和文件系统路径未必对齐。
实操建议：
- 右键点击项目中的入口文件（如
bin/www），选择 Copy Path → Copy Absolute Path，粘贴到JavaScript file栏中 - 确保
Working directory设为项目根目录（即含package.json的目录），否则require()可能因路径错乱加载失败 - 如果用 TypeScript 写 Koa（如
src/app.ts），JavaScript file必须指向编译后的dist/app.js，且tsconfig.json中sourceMap必须为true
Koa 中间件函数内设断点比顶层 app.listen() 更可靠
Koa 的执行模型是洋葱式中间件链，app.listen() 只是启动 HTTP server，真正业务逻辑藏在 app.use() 或路由处理器里。你在 app.listen(3000) 那行打断点，几乎永远停不住——因为那行只执行一次，且不涉及请求处理。
实操建议：
- 在具体路由 handler 里设断点，例如：
router.get('/api/user', async (ctx) => { /* 在这行打点 */ ctx.body = ... }) - 避免在
async函数最外层打点后立刻return，V8 有时会跳过帧信息；加一句console.log('debug')或赋值语句可稳定触发 - JPress（基于 Koa 的 CMS）通常有
routes/目录，优先在routes/post.js或middleware/auth.js里设断点，比在server.js入口更早命中
调试时环境变量 PORT 和 NODE_ENV 必须显式传入
Koa/JPress 默认监听 3000，但开发中常通过 PORT=3001 npm start 切换端口。WebStorm 不会自动读取 shell 环境或 .env 文件，若没手动配置，进程可能启动成功但无法访问，或因 NODE_ENV=production 导致日志被静默、中间件被跳过。
特色介绍： 1、ASP+XML+XSLT开发，代码、界面、样式全分离，可快速开发 2、支持语言包，支持多模板，ASP文件中无任何HTML or 中文 3、无限级分类，无限级菜单，自由排序 4、自定义版头（用于不规则页面） 5、自动查找无用的上传文件与空目录，并有回收站，可删除、还原、永久删除 6、增强的Cache管理，可单独管理单个Cache 7、以内存和XML做为Cache，兼顾性能与消耗 8、
实操建议：
- 在运行配置的
Environment variables栏填：PORT=3001;NODE_ENV=development（Windows 用^分隔） - 不要依赖
process.env.PORT || 3000的 fallback —— 调试时应让环境确定，避免歧义 - 如果用了
cross-env，别在Application parameters里重复写；WebStorm 的环境变量字段已覆盖其作用
attach 模式调试 Docker 中的 Koa 服务要改 host 和端口映射
本地跑 Koa 没问题，但 JPress 常部署在 Docker 里。直接用默认 localhost:9229 attach 会失败，因为容器内 --inspect-brk=127.0.0.1:9229 无法被宿主机连接。
实操建议：
- 启动容器时加参数：
node --inspect-brk=0.0.0.0:9229 ./bin/www，并确保-p 9229:9229映射端口 - WebStorm 新建
Attach to Node.js/Chrome配置，Host填localhost（不是127.0.0.1），Port填9229 - 关键细节：容器内源码路径（如
/app/bin/www）必须和 WebStorm 项目中文件路径一致，否则断点映射失效；可用docker cp检查或把代码挂载为 volume
调试 Koa/JPress 最容易被忽略的点是「断点位置」和「环境一致性」：框架代码本身不执行业务逻辑，真正干活的是你写的中间件和路由；而 WebStorm 调试器只认它加载的 JS 文件路径，不认你心里想的“应该在这儿停”。
