Laravel 11 异常处理核心迁移至 bootstrap/app.php 的 withExceptions() 配置，通过 report() 和 render() 方法实现类型安全的异常报告与响应渲染，并支持全局上下文注入。
Laravel 11 对异常处理和日志记录做了结构化升级，核心变化在于将异常管理从传统的 App\Exceptions\Handler 类逐步迁移至基于 bootstrap/app.php 中的 withExceptions() 配置方式。它更强调声明式配置、类型安全回调和统一上下文注入，而非重写整个 Handler 类。查看和配置的关键不在“改类”，而在“配闭包”。
查看当前异常处理配置入口
打开项目根目录下的 bootstrap/app.php 文件，定位到 ->withExceptions(...) 调用块。这是 Laravel 11 的异常处理中枢——所有报告（report）与渲染（render）逻辑都应在此注册，而非直接修改 Handler 类。
- 若该调用不存在，说明项目仍沿用旧版 Handler 模式，需手动添加；
- 若已存在，检查内部是否调用了
$exceptions->report(...)或$exceptions->render(...)； - 默认情况下，Laravel 11 不会生成空的
withExceptions块，需开发者显式启用才能覆盖默认行为。
配置自定义异常报告（log）
在 withExceptions 闭包中使用 report() 方法注册类型提示的异常处理器，实现按异常类型分流日志：
- 针对特定异常（如
App\Exceptions\PaymentFailedException），直接类型提示参数，Laravel 自动匹配：
$exceptions->report(function (PaymentFailedException $e) {
\Log::error('支付失败', [
'order_id' => $e->orderId,
'gateway' => $e->gateway,
'user_id' => auth()->id() ?? null
]);
});
- 想阻止该异常进入默认日志栈（比如已发给 Sentry），追加
->stop()； - 支持链式注册多个 report 回调，按注册顺序执行；
- 未被任何
report()匹配的异常，仍走默认日志配置（config/app.php中的log和log_level）。
配置异常渲染（response）逻辑
使用 render() 方法拦截异常并返回自定义响应，适用于 API 错误格式统一或前端友好提示：
- 可基于异常类型返回 JSON 响应（推荐 API 项目）：
$exceptions->render(function (ValidationException $e, $request) {
return response()->json([
'message' => '验证失败',
'errors' => $e->errors()
], 422);
});
- 也可返回视图（如自定义 500 页面）：
$exceptions->render(function (\Throwable $e, $request) {
if ($request->is('api/*')) {
return response()->json(['message' => '服务暂时不可用'], 503);
}
return response()->view('errors.custom-503', [], 503);
});
- 注意：render 回调必须返回
Response实例，否则抛出新异常； - 未被 render 拦截的异常，由框架默认渲染器处理（如显示 Whoops 或 500 页面）。
全局日志上下文与环境适配
所有通过 report() 或默认日志记录的异常，都会自动注入当前用户 ID（如已认证）。你还可以扩展全局上下文：
- 在
withExceptions闭包中调用context()方法：
$exceptions->context(function () {
return [
'app_version' => config('app.version'),
'environment' => app()->environment(),
'request_id' => request()->header('X-Request-ID') ?? Str::uuid()->toString(),
];
});
- 这些键值对会附加到每条异常日志的
context字段中，方便 ELK 或 LogViewer 过滤分析； - 确保
APP_LOG_LEVEL环境变量设置合理（如生产设为error），避免 debug 日志刷爆磁盘。
