如何通过实战掌握ThinkPHP中间件自动加载机制？

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

ThinkPHP 6 没有启用中间件自动加载——app/middleware.php 必须存在、必须返回数组、必须显式列出类名，否则中间件不会自动注册。

中间件类文件放哪才被自动加载

中间件类本身走的是 Composer PSR-4 自动加载机制，但前提是路径和命名空间完全合规：

• 文件必须放在 app/middleware/ 目录下（不能是 app/Middlewares 或 app/middleware/Auth）
• 文件名必须与类名严格一致，比如 CheckAuth.php → class CheckAuth
• 命名空间必须是 app\middleware（不是 app\Middlewares、App\Middleware 或省略）
• 类需继承 think\middleware 或直接实现 __invoke 方法

漏掉任一条件，运行时就会报 Class "app\middleware\CheckAuth" not found，而不是“没生效”。

app/middleware.php 不加载的典型表现

这个文件是全局中间件的唯一注册入口，但它不是“配置文件”，而是 PHP 脚本，执行后必须返回一个数组：

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

• 删了它、改名了、或写成 middleware.config.php → 中间件全失效，且无任何提示
• 写了 echo 'debug'; return [...]; → 返回值变成 NULL，$this->app->middleware->import() 接收空数组，静默跳过
• 多应用模式下（app/multi_app = true），全局中间件配置在 app/middleware.php 无效，得去对应应用目录（如 app/admin/middleware.php）单独配
• 用 Swoole 或 RoadRunner 时，若中间件类未在 Worker 启动前被 autoload 加载过，首次请求可能触发 Class not found（因 PSR-4 映射未热加载）

中间件注册后仍不执行的常见原因

注册成功 ≠ 执行成功。洋葱模型下，中间件是否跑起来，还取决于调用链是否完整：

• 路由中间件必须用 middleware() 显式绑定，比如 Route::get('user', 'User@index')->middleware(CheckAuth::class)；光注册不调用，等于没写
• 全局中间件顺序错位：比如 Lang 中间件放在 SessionInit 之前，Lang::detect() 就读不到 session 数据，语言切换失败
• 中间件里提前访问 Request 或 Session 的数据（比如在 __construct() 里调 session('user')），此时请求上下文尚未初始化，会返回空或抛异常
• 终止请求时没返回 Response 实例：用 echo、print_r 或直接 return null，会导致后续中间件和控制器不执行，且无错误日志

最常被忽略的一点：中间件类文件路径、命名空间、app/middleware.php 返回值三者必须严丝合缝。少一个反斜杠、多一个大写字母、返回值被调试语句污染——都足以让整个中间件栈静默失效。