中间件没生效最常见原因是注册顺序错误：必须在路由前调用app.Use()；漏调ctx.Next()或未用ctx.StopExecution()会导致流程中断；ctx.Values()传值失效多因key类型不一致或拼写错误。
中间件没注册到匹配的路由上
最常见的情况是：写了中间件函数，也调用了 app.Use() 或 group.Use()，但请求路径根本没进这个分组。Iris 的中间件只对注册时绑定的路由前缀生效，比如 admin := app.Party("/admin") 后调用 admin.Use(auth)，那 /api/login 就完全不会触发它。
检查点：
- 确认当前请求的完整路径（如
/admin/users）是否落在该 Party 的前缀下 - 如果用了嵌套 Party（如
users := admin.Party("/users")），中间件必须在父或子 Party 上显式.Use()，不会自动继承 -
app.Use()注册的是全局中间件，但若你用的是app.Get("/path", handler)这种直写方式，它不经过任何Use()链——得改用app.Get("/path", middleware, handler)显式插入
OPTIONS 预检请求绕过了中间件
跨域请求发 OPTIONS 时，如果没显式注册对应路由，中间件根本不会执行。Iris 不会自动捕获未注册的 OPTIONS 方法，哪怕你在中间件里写了 if ctx.Method() == "OPTIONS" 判断也没用——因为路由不匹配，中间件压根不进。
必须做两件事：
- 用
app.Options("*", corsHandler)或group.Options("/api/*", corsHandler)显式注册 OPTIONS 路由 - 在该 handler 里手动设置所有 CORS 头（
Access-Control-Allow-Origin等）和安全头（X-Content-Type-Options等），不能只靠ctx.Next()
中间件内部提前返回却没调 ctx.StopExecution()
Iris 不像其他框架那样遇到 return 就自动中断。如果你在中间件里写了 ctx.StatusCode(401); ctx.WriteString("no auth"); return，后续中间件和 handler 仍会继续执行，可能造成重复写响应、panic 或逻辑错乱。
正确姿势：
- 所有提前终止逻辑后，必须紧跟
ctx.StopExecution() - 不要在
ctx.StopExecution()后再调ctx.Next()，会 panic - 典型错误场景：JWT 验证失败返回 401，但忘了
StopExecution，结果鉴权中间件之后的日志中间件、DB 查询 handler 全都照常跑
中间件注册顺序导致被跳过
Iris 中间件按注册顺序依次执行，但某些操作会让后续中间件“失效”。比如你在某个中间件里调了 ctx.RecordRequestBody(true) 或提前读了 ctx.Request().Body，又没重置，后面的中间件（如签名验证）就读不到原始 body；或者你在安全头中间件里把 X-Frame-Options 设在 ctx.Next() 之后，而前面的 CORS 中间件已写过同名 header，结果被覆盖。
关键原则：
- 设响应头（尤其是安全头、CORS 头）必须放在
ctx.Next()之前 - 读取并重置
ctx.Request().Body的逻辑，必须在所有依赖原始 body 的中间件之前完成 -
UseGlobal()注册的中间件优先级最高，最先执行；父子 Party 的中间件按注册路径顺序叠加，不是按代码书写顺序
