Laravel如何根据不同请求类型定制异常响应渲染策略？

本文共计916个文字，预计阅读时间需要4分钟。

API 请求抛出异常时返回 JSON，网页请求抛出异常时返回 Blade 页面——这件事不能依赖于中间件或控制器底层处理，必须直接在 `App\Exceptions\Handler::render()` 这里进行判断。

怎么区分 API 和网页请求

别依赖路由前缀（比如 api/*）或手动传参，Laravel 自带两个可靠判断方式：

• $request->expectsJson()：检查请求头是否含 Accept: application/json 或是 AJAX（X-Requested-With: XMLHttpRequest），绝大多数前端框架（Axios、Fetch）默认带上
• $request->is('api/*')：只匹配 URL 路径，适合你明确把所有 API 放在 /api/ 下的项目，但注意它不识别子域名或版本前缀（如 v1.api.example.com）
• 两者可以组合用：if ($request->expectsJson() || $request->is('api/*'))，兼顾灵活性和兼容性

常见异常类型要单独处理

直接 return parent::render($request, $exception) 会走默认逻辑，对 API 来说就是暴露堆栈（调试模式下）或空白 500 页面（生产环境），必须提前拦截：

• ModelNotFoundException：对应 404，API 返回 response()->json(['message' => 'Not found'], 404)，网页返回 response()->view('errors.404')
• ValidationException：Laravel 自动捕获 $request->validate() 抛出的异常，API 返回 response()->json(['errors' => $exception->errors()], 422)，网页可重定向回表单页或显示错误提示
• AuthorizationException：权限不足，统一返回 403，API 和网页都建议用 JSON 格式，避免前端解析 HTML 错误页
• 不要 catch Exception 或 Throwable 做兜底——这会吞掉本该触发调试器的致命错误，比如内存溢出、语法错误

为什么不能在中间件里统一转 JSON

因为异常可能发生在中间件执行之前（比如路由未匹配、服务容器绑定失败）或之后（比如视图渲染时报错），中间件根本没机会运行。典型例子：

• 访问一个不存在的路由 → 触发 NotFoundHttpException → 此时还没进任何中间件
• Blade 模板里写了 {{ $user->name }} 但 $user 是 null → 视图引擎报错 → 中间件早已执行完毕
• 数据库连接失败导致 Eloquent 查询抛出 QueryException → 发生在模型方法内部，远早于响应构造阶段

APP_DEBUG=true 时 JSON 响应仍被覆盖？

开发环境下 Laravel 默认返回带堆栈的 HTML 错误页，哪怕请求头是 Accept: application/json。解决办法是在 render() 开头加强制判断：

if ($request->expectsJson()) { return response()->json([ 'message' => 'Server Error', 'debug' => config('app.debug') ? $exception->getMessage() : null ], 500); }

注意：别在生产环境返回 $exception->getMessage()，容易泄露路径、数据库名等敏感信息；config('app.debug') 是唯一安全的开关依据。

真正容易被忽略的是第三方 SDK 抛出的异常——比如 Stripe、PayPal 的客户端库，它们往往用原生 Exception，不会自动进你的 ValidationException 分支。这类异常得手动补一层判断，或者在调用处 try/catch 后重新 throw new CustomPaymentException()，否则就静默变成 500 HTML 页了。