先说几个核心判断：ThinkPHP 的中间件机制，其实就那么几块硬骨头啃透了，剩下的就是套路。很多开发者在这个环节踩坑，往往不是因为概念多复杂，而是几个关键细节没扣死。下面把这几个最容易出问题的点拆开揉碎了说清楚，希望能帮你少走弯路。
中间件执行链靠 $next($request) 驱动，不是自动调用
别指望写个类文件，框架就自动把它挂到执行链上——ThinkPHP 的中间件没那么“智能”。它靠的是显式调用 $next($request) 来把请求往下传，这背后是经典的管道模式（Pipeline），所有中间件被串成一个洋葱圈。你每剥开一层，$next 就是通往下一层的唯一通道。一旦漏掉 return $next($request)，相当于在管道中间剪断了水管，后面的中间件、控制器、视图全部被截停，浏览器收不到任何响应，日志里也找不到蛛丝马迹。
handle()方法必须返回一个thinkResponse实例，光是调用$next($request)而不return，等于白干。- 遇到分支逻辑，比如鉴权失败要重定向，必须保证所有路径都有返回值：
if分支返回redirect()，else 分支老老实实跟上return $next($request)。 - 后置处理要写在
$next($request)之后，操作它返回的$response对象，比如$response->header('X-Trace', 'done')。
中间件注册点只有三处，少一个都不加载
写了类文件不等于框架认得它，这可能是最容易被忽略的坑。ThinkPHP 只认三个注册位置，缺一不可：
- 全局注册：修改
app/middleware.php（TP6/TP8 单应用）或config/middleware.php（多应用），返回一个数组，元素必须是完整的类名字符串，比如'appmiddlewareAuthCheck'或appmiddlewareAuthCheck::class。 - 路由级注册：在
route/app.php中链式调用middleware()，支持类名、别名（需提前映射）、数组，例如Route::get('api/user', 'Api/User')->middleware(['auth', 'throttle'])。 - 控制器级注册：在控制器属性
$middleware中声明，或构造函数中调用$this->middleware()，还可以带条件过滤，比如['CheckRole' => ['only' => ['delete']]]。
常见错误：类文件放在 app/middleware/auth/AuthCheck.php，但框架默认不扫描子目录；命名空间写成 appmiddlewareauthAuthCheck，文件却实际摆在根 middleware 目录下。这种错位，框架不会报错，只会静默忽略。
$request->post() 为空？多半是前面中间件已读空输入流
PHP 的 php://input 流有个特性：只能读一次。$request->post() 和 $request->input() 底层都依赖这个流。一旦前面任何一个中间件（包括框架内置的 ValidatePostSize）调用了它们，后面再调用就返回空数组——这不是 Bug，是 PHP 自身的机制。
- 安全做法：统一改用
$request->param()，它由框架缓存解析结果，多次调用也不会有副作用。 - 如果必须读原始流（比如验签加密 payload），那只能在第一个执行的中间件里一次性读取，并且不能混用
post()/input()。 - Session 数据在中间件里可能还不可用，因为
SessionInit中间件通常排在后面执行，务必确认执行顺序。
中间件参数传递必须注册时显式声明
想往 handle() 里传额外参数，比如角色白名单，不能靠构造函数注入，必须在注册时以数组形式声明：
- 路由注册：
->middleware(['check_role' => ['admin', 'editor']]) - 控制器注册：
protected $middleware = [appmiddlewareCheckRole::class => ['admin', 'editor']] - 对应
handle()签名必须匹配：public function handle($request, Closure $next, $role1, $role2)
没按注册格式传参，框架不会自动解包，参数会丢失；参数个数与注册数组长度不一致，直接抛出 ArgumentCountError。
说到底，中间件真正起效的临界点其实很薄：注册位置对不对、返回语句写没写、流读取时机是否冲突、参数声明是否匹配。任意一环出错，都会导致静默失效。线上问题排查时，优先盯住这四块，比翻源码快得多。
