根本原因是ThinkPHP异常处理未按JSON流程执行：请求未带Accept头或不匹配API路由时，框架fallback至HTML输出，且异常发生在控制器json()调用前，导致返回HTML错误页而非JSON。
为什么前端收到的是HTML错误页而不是JSON
根本原因不是代码写错，而是ThinkPHP在异常或正常响应阶段没按预期走JSON流程。框架默认根据Accept头、URL后缀或default_return_type配置决定输出格式，而多数API请求（如fetch、Axios默认配置）不带Accept: application/json，框架就fallback到HTML——哪怕你在控制器里写了json()，异常发生时也早于那行代码。
-
render()方法没做$request->expectsJson()或路由前缀判断，直接返回HTML视图 - 用了
throw new Exception()但没被中间件拦截，走到框架默认异常处理器，它只认X-Requested-With: XMLHttpRequest，现代请求基本不带这个头 - 全局中间件注册顺序不对，比如
UniformJsonResponse被放在缓存中间件之后，响应已被缓存并发出 - 控制器里调了
$this->fetch()或模板相关方法，触发了HTML渲染流程，覆盖了后续json()
怎么快速确认当前响应是不是被强制设成HTML
直接看HTTP响应头里的Content-Type。用浏览器开发者工具或curl检查：
curl -I http://your-api.com/api/user
如果返回Content-Type: text/html; charset=utf-8，说明框架已进入HTML输出路径。这时要查三处：
- config/app.php中
'default_return_type' => 'html'是否被全局设为'html'（别改这里，这是整站默认值） - 有没有中间件在
$next($request)前就调了response()->view()或view()并没包response() - 当前请求的
$request->path()是否匹配了非api/开头的路由，导致进了Web控制器而非API控制器
Controller里return json()却仍出HTML的常见陷阱
不是json()失效，而是它根本没被执行。典型场景：
立即学习“PHP免费学习笔记（深入）”；
- 验证失败抛出
ValidateException，但你没在app/exception/Handler.php的render()里处理它，框架用默认逻辑返回HTML错误页 - 路由未匹配（404）或方法不存在（405），这类框架级异常不经过控制器，
json()完全没机会运行 - 中间件里
throw new HttpException(401)，但render()没识别$e instanceof HttpException就返回JSON - 写了
return json([...])，但前面有exit、die或未捕获的致命错误（如Call to undefined method），PHP直接中断
最稳的JSON兜底方案：中间件+render()双保险
仅靠控制器json()或仅靠render()都不够。必须两者配合，且中间件优先级要高：
- 写一个全局中间件，在
$next($request)之后检查响应类型：if ($response instanceof Response && $response->getOriginalData() !== null && !is_string($response->getOriginalData())) { $response = json($response->getOriginalData()); } - 在
Handler.php的render()开头加判断：if ($request->expectsJson() || $request->routeIs('api.*') || strpos($request->path(), 'api/') === 0) { return response()->json(['code' => $code, 'msg' => $e->getMessage()], $code); } - 确保该中间件注册在
app/middleware.php中位于ResponseTrace之后、SessionInit之前，避免被其他中间件提前终止 - 别在
render()里直接return json(...)，这会丢失状态码；必须用response()->json()或response(..., $code)
真正容易被忽略的是：路由未匹配和参数解析失败这两类异常，它们发生在控制器执行前，根本不会进你的login()方法，所以任何控制器内的json()都无效——只能靠中间件层或render()兜底。
