handle()必须返回Response实例，因PSR-15强制类型约束：漏写return、echo/exit中断、未return json()/abort()等均导致null返回而报TypeError；正确做法是所有分支显式return Response对象。
报 TypeError: Return value must be an instance of Psr\Http\Message\ResponseInterface，说明中间件 handle() 方法没返回 Response 实例——不是框架 bug，是 PSR-15 强制类型约束触发的拦截。
为什么 handle() 必须返回 Response 实例
ThinkPHP 6+ 的中间件完全遵循 PSR-15 规范，handle() 是唯一入口，签名固定为 handle($request, \Closure $next)，且返回值类型被硬性声明为 ResponseInterface。PHP 8+ 会直接抛出 TypeError；PHP 7.x 虽不报错，但框架后续无法处理 null 或 array，导致白屏或静默失败。
- 漏写
return（比如只写了$next($request)）→ PHP 默认返回null - 用
echo/die/exit中断流程 → 没有返回值 - 返回了
json(['code'=>200])但没加return→ 同样是null - 调用了
abort(403)却没接return→ 异常抛出后函数未终止，末尾仍隐式返回null
正确写法：每个分支都显式 return
无论放行还是拦截，所有逻辑路径终点都必须是 return 一个 Response 对象。常见模式如下：
- 放行：必须写
return $next($request)，不能只写$next($request) - JSON 拦截：
return json(['code' => 403, 'msg' => '无权限']) - 重定向：
return redirect('/login') - 视图响应：
return view('error/403') - 手动构造：
return response()->code(401)->header('Content-Type', 'application/json')
继承 BaseMiddleware 可避免手写类型提示
直接实现 MiddlewareInterface 需自己声明返回类型，容易遗漏。更稳妥的做法是继承 think\middleware\BaseMiddleware：
- 它已预设好
handle()的完整签名和返回类型提示 - 自动兼容
think\Response和 PSR-15ResponseInterface - 生成命令
php think make:middleware AuthCheck默认就继承它 - 若手动创建类，开头必须加
use think\middleware\BaseMiddleware;并extends BaseMiddleware
调试时别用 dump()，用 trace() 看执行流
报类型错误时，光看报错堆栈很难定位是哪个中间件漏了 return。用 trace() 在 handle() 开头打点，比 dump() 更安全：
public function handle($request, \Closure $next)
{
trace('AuthCheck middleware entered', 'info');
if (!Auth::check()) {
return json(['code' => 401]);
}
return $next($request); // 这行不能少
}
如果日志里只看到 “entered” 却没走到 return $next() 分支，说明前面某处提前中断或没走完逻辑——重点查条件判断是否覆盖全部路径。
最易被忽略的是多层嵌套 if/else 或早期 return 导致末尾 return $next($request) 实际不可达。务必确保函数体最后一行是明确的 return，哪怕只是兜底放行。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
