ThinkPHP中间件如何实现功能及配置步骤详解？

本文共计855个文字，预计阅读时间需要4分钟。

ThinkPHP中间件不是可有可无的装饰，而是控制请求生命周期关键开关——它能在请求到达控制器前做鉴权、解析参数、记录日志，也能在响应发出前修改头信息、压缩内容、注入数据。

中间件类文件放哪、怎么命名才不报 Class not found

类必须放在 app/middleware/ 目录下，文件名和类名严格一致（比如 CheckAuth.php 里必须定义 class CheckAuth），命名空间固定为 app\middleware，不能写成 App\Middleware 或 app\Middlewares。

• 多应用模式下路径是 app/{app_name}/middleware/，别漏掉应用名
• 类需继承 think\Middleware 或实现 __invoke 方法
• 如果用了 Swoole / RoadRunner，确保类已提前加载（避免运行时 autoload 失败）

全局中间件为什么没生效

app/middleware.php 是唯一入口，它必须存在、必须返回数组、且不能有 echo 或 return null 等干扰语句。

• 常见错误：删了这个文件、改名、或写了调试语句导致返回非数组
• 数组元素必须是完整类名字符串，如 'app\middleware\AuthMiddleware'，不能只写 'AuthMiddleware'
• 若启用了多应用模式，全局配置不生效，得去对应应用目录下配 app/admin/middleware.php

路由级中间件调用后完全没触发

光写 Route::get('admin', 'Admin/index') 不会触发任何中间件；必须显式链式调用 ->middleware('auth') 或 ->middleware(AuthMiddleware::class)。

立即学习“PHP免费学习笔记（深入）”；

• 字符串形式的中间件名（如 'auth'）需先在 app/middleware.php 中注册别名
• 链式调用顺序决定执行顺序：->middleware(A::class)->middleware(B::class) 表示 A 在请求阶段先执行
• 分组路由中，middleware() 必须写在 Route::group() 之后、闭包之前，否则无效

中间件里读不到 POST 数据或 Session

不是框架 bug，是生命周期问题：中间件在路由解析、Session 初始化、input() 解析完成前就运行了。

• Session 尚未启动时，session('user_id') 可能为空；优先用 think\facade\Session::get()
• $request->param() 在中间件里可能不可用；改用 $request->post() 或 $request->get() 显式取值
• POST 数据只能读一次：前面中间件调过 $request->post()，后面再调就为空；建议统一用 $request->param()（它内部做了缓存）
• 需要原始 body（如 JSON），应在第一个中间件用 $request->getContent() 读一次，并通过 $request->withAttribute() 存入属性供后续复用

最隐蔽也最高频的问题：忘了在 handle() 里 return $next($request)。漏掉这行，整个请求链就断了，浏览器卡住或返回空响应——因为 PHP 返回 null，框架视作响应中断，连数据库连接都可能没释放。