中间件调试失败主因是断点未命中执行路径、next()被跳过或调试器未进入函数体；需确认服务启动、发送真实请求、正确配置launch.json、断点打在中间件函数体内，并注意异步调试局限与中间件顺序。
中间件调试失败，90% 是断点没打在执行路径上、next() 被跳过、或调试器根本没进中间件函数体——不是代码写错了，而是 Node.js 的异步执行链和 VSCode 的断点触发机制没对齐。
中间件里加了 debugger 却没停住
这是最常见错觉：以为写了 debugger 就能停，但实际它只在当前 JS 执行上下文有效。Koa/Express 中间件是被框架调用的回调函数，如果整个请求没发出去（比如没启动 server），或者请求被前置中间件截断（如 404 或 auth 拒绝），debugger 根本不会执行。
- 确认服务已真正启动：
node app.js后看到类似Server is listening on port 3000日志 - 用
curl或 Postman 发一个真实请求（不能只打开浏览器地址栏，某些中间件会检查Content-Type或 method） - 把
debugger放在中间件最开头，并在它前面加一行console.log('→ middleware hit')，看日志是否输出
launch.json 配置必须匹配中间件运行方式
中间件不是独立脚本，它依附于整个 HTTP server 生命周期。直接用 "request": "launch" 调试入口文件（如 app.js）是对的，但容易漏掉关键配置：
-
"program"必须指向真正启动 server 的文件，比如${workspaceFolder}/src/server.js，而不是index.js（后者可能只是导出模块） - 务必设
"console": "integratedTerminal"，否则console.log不输出，你无法判断中间件是否被调用 - 如果用了
nodemon，不要改type，而是在runtimeExecutable和runtimeArgs里指定："runtimeExecutable": "${workspaceFolder}/node_modules/.bin/nodemon", "runtimeArgs": ["--inspect-brk", "${workspaceFolder}/src/server.js"]
断点打在哪才真正生效
中间件函数本身是同步定义的，但执行是异步的。VSCode 断点只对「实际被执行的代码行」有效，不是「被加载的代码行」。
- 别在
app.use(middleware)这行打点——这只会停在注册阶段，不是执行阶段 - 断点必须打在中间件函数体内，比如 Koa 中：
async (ctx, next) => { /* ← 在这里打 */ console.log(ctx.url); await next(); } - 如果中间件是
require('./auth')导入的，确保./auth.js路径正确，且该文件确实被require到了（可临时加console.log('auth loaded')验证） - 对 Express，注意
next('route')会跳过后续中间件，断点可能永远不触发
异步中间件里 await next() 后变量看不到
这是 V8 调试器的老问题：当执行流进入 microtask 队列（比如 Promise.then 或 await 后），VSCode 有时无法保留上一帧的闭包变量，导致“变量面板为空”或“ctx 显示为 undefined”。
- 不要依赖“变量”面板自动展开，把鼠标悬停在
ctx上，看 tooltip 是否显示内容；悬停比面板更可靠 - 在
await next()后立刻加一行console.log(ctx.body)，验证数据是否还在 - 避免在
try/catch外层包裹整个中间件——错误捕获逻辑可能干扰调试器对作用域的识别
最麻烦的其实是中间件顺序：断点打了，也触发了，但你调试的不是你以为的那个中间件。HTTP 请求经过的链条，和你代码里 app.use() 的顺序严格一致，差一行就可能完全绕过目标逻辑。动手前，先用 console.trace() 把调用栈打出来，比猜快得多。
