必须在app/middleware.php中注册为全局中间件才能拦截所有请求，但需注意其会误拦静态资源；推荐结合SessionInit初始化、路由分组隔离及日志验证确保精准生效。
如果您在ThinkPHP项目中希望某个中间件对所有HTTP请求生效，但发现部分接口未被拦截或静态资源被误拦，则可能是由于中间件注册位置、作用域或执行层级配置不当。以下是实现中间件全局应用的具体操作步骤：
一、在app/middleware.php中注册全局中间件
全局中间件必须通过app/middleware.php文件显式返回类名数组来启用，该文件是框架识别全局中间件的唯一入口，注册后将覆盖所有Web请求（含CLI需手动排除）。类名必须为完整命名空间字符串，且对应类文件须严格符合PSR-4规范。
1、打开项目根目录下的app/middleware.php文件。
2、确认文件返回值为索引数组，格式为return ['app\middleware\AuthCheck']，其中AuthCheck为中间件类全限定名。
立即学习“PHP免费学习笔记（深入）”；
3、确保中间件类文件位于app/middleware/AuthCheck.php，类定义命名空间为app\middleware，并继承think\Middleware或实现__invoke方法。
4、若需跳过特定路径（如登录页），可在数组中使用键值对形式传递配置：['app\middleware\AuthCheck' => ['except' => ['/login', '/captcha']]]。
二、启用Session初始化中间件以支撑权限校验
多数全局权限中间件依赖Session数据，而Session需由框架内置中间件提前初始化，否则session('user_id')等调用将始终为空。该中间件必须作为全局中间件注册，且应置于自定义中间件之前以确保状态可用。
1、在app/middleware.php数组开头添加\think\middleware\SessionInit::class。
2、检查config/session.php中'auto_start' => true已启用，且'type'驱动配置正确（如'file'或'redis'）。
3、若项目运行于CLI环境（如队列任务），需在中间件handle方法内添加判断：if (app()->isCli()) return $next($request);，防止Session初始化失败导致崩溃。
三、避免全局中间件误拦静态资源与公共接口
全局中间件默认作用于所有HTTP请求，包括public/目录下的JS、CSS、图片及登录、验证码等无需鉴权的接口，易引发白屏或403错误。不能依赖中间件内部硬编码路径判断，而应在路由层结构化隔离。
1、在route/app.php中为免鉴权路由显式命名：Route::get('login', 'Login/index')->name('login');。
2、将公共API接口归入独立分组，并仅绑定限流等非鉴权中间件：Route::group('api', function () { Route::post('login', 'Api/Login/login'); })->middleware('throttle:10,1');。
3、对后台管理路由统一使用分组绑定：Route::group('admin', function () { Route::get('index', 'Admin/index'); })->middleware('app\middleware\AuthCheck');，确保鉴权仅作用于业务路径。
四、验证中间件是否实际执行
中间件注册后不生效的常见原因是类加载失败、命名空间错误或handle()方法缺失返回值。需通过日志与响应行为交叉验证其真实执行状态，而非仅依赖代码存在。
1、在中间件handle()方法首行插入trace('AuthCheck executed');，查看runtime/log目录下日志是否输出。
2、在handle()中添加强制中断逻辑：if (true) return json(['code' => 999, 'msg' => 'test']);，访问任意页面确认是否立即返回该JSON。
3、检查浏览器开发者工具Network面板，确认响应头中X-Powered-By或自定义Header是否被中间件注入，以此判断洋葱模型是否进入该层。
4、若使用Swoole或RoadRunner，需确认中间件类已在服务启动时预加载，禁止依赖运行时autoload动态载入，否则首次请求可能报Class not found。
