ThinkPHP6.0如何注册全局中间件_ThinkPHP6.0全局配置【设置】

先说几个核心判断：ThinkPHP6.0的全局中间件注册机制，是很多开发者从5.x版本升级后容易踩坑的地方。表面上看只是改一个配置文件，但实际上涉及命名空间解析、自动加载、多应用隔离三层逻辑。这篇文章会把这件事彻底说清楚。

全局中间件必须在 app/middleware.php 中注册，而不是在 config/middleware.php

后者仅用于中间件配置项（如是否启用、参数等），不负责注册逻辑。这是ThinkPHP6.0的一个关键设计变更，必须从一开始就明确。

为什么 config/middleware.php 不能注册中间件？

ThinkPHP6.0 把「中间件定义」和「中间件配置」彻底分离：

• config/middleware.php 只控制中间件的开关、顺序权重、条件启用等元信息，比如 'http_cache' => ['enabled' => false]
• 真正要让中间件生效，必须在 app/middleware.php 返回一个数组，列出所有要全局执行的中间件类名或闭包
• 如果只改了 config/middleware.php 却没在 app/middleware.php 里写，中间件完全不会运行

这就好比钥匙和锁的关系：config/middleware.php 是锁上的配置项，它决定这把锁要不要用、怎么用；而 app/middleware.php 才是那把真正的钥匙，没有它，锁永远打不开。

app/middleware.php 的正确写法

该文件必须返回一个数组，每个元素是中间件类的完整命名空间字符串，或匿名函数。常见的错误五花八门，但最核心的就那几种：

• ✅ 正确示例（类名字符串）：return [ \think\middleware\AllowCrossDomain::class, \app\middleware\CheckAuth::class ];
• ✅ 正确示例（闭包）：return [ function ($request, \Closure $next) { return $next($request)->header('X-Powered-By', 'TP6'); } ];
• ❌ 错误写法：use think\middleware\AllowCrossDomain; return [AllowCrossDomain::class];（use 在此文件中被忽略）
• ❌ 错误写法：return ['think\middleware\AllowCrossDomain']（缺少反斜杠，PHP 自动解析为当前命名空间下类）

这里有个容易被忽视的细节：app/middleware.php 文件不支持 use 语句。很多开发者习惯了在其他地方用简写，结果在这里翻车。必须使用完整的、带反斜杠的类名字符串。

中间件注册后不生效的典型原因

即使写对了 app/middleware.php，仍可能因以下原因失效：

• 中间件类本身没有实现 __invoke 方法或继承 think\middleware\Middleware 基类
• 中间件类路径错误，比如文件实际在 app/middleware/CheckAuth.php，但注册写成 \app\middleware\checkauth::class（大小写敏感）
• 应用处于多应用模式，而你在全局 app/middleware.php 注册，但请求走的是某个子应用（如 admin），此时应改用该子应用下的 app/admin/middleware.php
• 中间件被路由级或控制器级中间件覆盖：全局中间件优先级最低，会被更具体的中间件禁用或跳过

需要注意的是：中间件类文件必须存在、命名空间与路径严格一致、且不能依赖 use 简写——所有路径都得是绝对的、带反斜杠的完整字符串。这些看似细小的规范，往往是排查问题时最容易忽视的盲区。

如何验证中间件是否已加载

最直接的办法是加日志或断点：

• 在中间件 __invoke 方法开头插入 trace('CheckAuth running');，然后访问接口看 Trace 日志是否出现
• 用命令行检查中间件列表：php think middleware:list（需确保 think 命令可用，且中间件类能被自动加载）
• 注意：该命令只显示已注册且可反射的类，闭包中间件不会出现在列表中

全局中间件注册这件事，表面只是改一个文件，但背后涉及命名空间解析、自动加载机制、多应用隔离三层逻辑。最容易被忽略的是：中间件类文件必须存在、命名空间与路径严格一致、且不能依赖 use 简写 —— 所有路径都得是绝对的、带反斜杠的完整字符串。记住这一点，能帮你省下大把排查时间。