ThinkPHP中间件需显式注册才能生效，常见错误包括未在app/middleware.php或路由中挂载、类名拼写错误、未返回$next($request)导致请求中断、重复读取POST数据失败、异常未捕获致白屏。
中间件注册位置不对，逻辑根本不会执行
ThinkPHP 的中间件必须显式注册才能生效，不是写完类就自动触发。常见错误是只创建了中间件类，却忘了在 app/middleware.php 或路由定义里挂载。
实操建议：
- 全局生效：在
app/middleware.php中追加类名字符串，例如['app\middleware\AuthCheck'] - 路由级生效：调用
middleware()方法，如Route::get('admin', 'Admin/index')->middleware('auth')，前提是该中间件已在配置中别名映射 - 控制器级：在控制器构造函数中调用
$this->middleware('check');，注意仅对当前控制器方法有效
容易踩的坑：app/middleware.php 返回的是数组，但若中间件类名拼错、命名空间没写全，或类文件未遵循 PSR-4 规范（比如文件名不是 AuthCheck.php），会直接报 Class not found 错误，且无明确提示指向中间件加载环节。
中间件 handle() 方法里忘记 return $next($request)
这是最隐蔽也最高频的问题：中间件执行完前置逻辑后，如果不显式调用并返回 $next($request)，后续所有中间件和目标控制器将被“截断”，请求直接终止，浏览器可能卡住或返回空响应。
立即学习“PHP免费学习笔记（深入）”；
正确写法示例：
public function handle($request, Closure $next)
{
if (!session('user_id')) {
return redirect('/login');
}
return $next($request); // ← 这一行不能少，也不能写成 $next($request);（没 return）
}
为什么这样做：ThinkPHP 中间件链是洋葱模型，$next($request) 是进入下一层的唯一入口；漏掉 return 会导致 PHP 返回 null，框架将其视作响应中断。
性能影响：即使只做日志记录，也必须 return，否则整个请求生命周期提前结束，连数据库连接都可能没释放。
想在中间件里读取 POST 数据，但 $request->post() 返回空
原因很直接：POST 数据只能被读取一次。如果前面已有中间件（比如框架自带的 ValidatePostSize 或你自定义的日志中间件）调用了 $request->post()、$request->input() 或 $request->rawInput()，后续中间件再调就会为空。
解决路径：
- 优先用
$request->param()—— 它兼容 GET/POST/ROUTE，且 ThinkPHP 内部做了缓存，多次调用不丢数据 - 若必须处理原始 body（如 JSON 接口），应在第一个中间件里用
$request->getContent()读一次，并通过$request->withAttribute()存入属性，供后续中间件复用 - 避免在多个中间件里重复解析
php://input，PHP 层面不可逆
兼容性注意：PHP 8.1+ 对 php://input 的读取更严格，未开启 enable_post_data_reading 时可能直接失败，而 ThinkPHP 默认已处理，所以尽量别绕过框架封装直接操作流。
中间件中抛异常，但没被统一捕获，页面显示白屏或堆栈
ThinkPHP 默认只捕获控制器层抛出的 HttpException 和部分系统异常，中间件里 throw 的任意 Exception 都会穿透到 PHP 默认错误处理器，导致开发环境显示堆栈、生产环境白屏。
实操建议：
- 在中间件内主动 try/catch，转为返回规范响应，例如：
return json(['code'=>500, 'msg'=>'验证失败']); - 如需复用全局异常处理，可手动触发：
throw new hinkException('xxx', 500);，但注意这仍需确保异常类被正确识别 - 更稳妥的做法是让中间件只负责“判断”，把具体错误响应交给控制器或
app/exception.php统一处理，中间件只 return redirect 或 json 即可
容易被忽略的地方：中间件的错误不会走 app/exception.php 的 render 方法，除非你显式 throw 并且该异常类继承自框架支持的基类；多数时候，它就是个裸异常，框架不管。
