错误处理 - Knowledge of Laravel

概述

创建 Laravel 项目后，错误与异常处理已预先配置好。自定义配置可在 bootstrap/app.php 的 withExceptions 方法中进行。

异常处理流程

下面展示了从异常发生到返回响应给客户端的流程。

// bootstrap/app.php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions): void {
        // 在此处配置异常的报告与渲染
    })->create();

传入 withExceptions 闭包的 $exceptions 对象是 Illuminate\Foundation\Configuration\Exceptions 的实例，用于管理整个应用的异常处理。

调试设置

config/app.php 的 debug 选项控制错误信息的显示量。默认使用 .env 中 APP_DEBUG 环境变量的值。

# 本地开发
APP_DEBUG=true

# 生产环境
APP_DEBUG=false

在生产环境中 APP_DEBUG 必须为 false。若保持为 true，机密信息可能被暴露给终端用户。

异常的报告

异常的报告，是指将异常记录到日志或发送到 Laravel Nightwatch、Sentry、Flare 等外部服务的处理。默认情况下会基于 config/logging.php 的配置记录到日志。

自定义报告回调

若希望根据异常类型进行不同的报告处理，可向 report 方法传入闭包。 Laravel 会根据闭包的类型提示判断异常类型。

use App\Exceptions\InvalidOrderException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->report(function (InvalidOrderException $e) {
        // 例如通知外部服务
    });
})

即便注册了自定义回调，默认的日志记录仍会继续。若要阻止向默认流程传播，可调用 stop() 或返回 false。

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->report(function (InvalidOrderException $e) {
        // ...
    })->stop();
})

`report()` 辅助函数

如果只想报告异常而不显示错误页，可以使用 report() 辅助函数。

public function isValid(string $value): bool
{
    try {
        // 校验处理...
    } catch (Throwable $e) {
        report($e);

        return false;
    }
}

report() 辅助函数可以在不中断向用户返回响应的情况下记录错误。适合后台任务或非关键处理的异常处理。

防止重复报告

同一个异常实例多次传入 report() 时，可能会在日志中产生重复条目。设置 dontReportDuplicates() 后，同一实例只会记录第一次。

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontReportDuplicates();
})

$original = new RuntimeException('Whoops!');

report($original); // 会被记录

try {
    throw $original;
} catch (Throwable $caught) {
    report($caught); // 被忽略（同一实例）
}

全局日志上下文

若希望为所有异常日志附加公共信息，可以使用 context 方法。当前用户 ID 若可用会被自动附加。

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->context(fn () => [
        'app_version' => config('app.version'),
    ]);
})

为异常类添加 `context()` 方法

在异常类自身定义 context() 方法后，可以将该异常特有的上下文信息包含在日志中。

<?php

namespace App\Exceptions;

use Exception;

class InvalidOrderException extends Exception
{
    public function __construct(
        private readonly int $orderId,
        string $message = '',
    ) {
        parent::__construct($message);
    }

    /**
     * 返回异常的上下文信息
     *
     * @return array<string, mixed>
     */
    public function context(): array
    {
        return ['order_id' => $this->orderId];
    }
}

日志级别的更改

若希望以特定日志级别记录特定异常，可使用 level 方法。

use PDOException;
use Psr\Log\LogLevel;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->level(PDOException::class, LogLevel::CRITICAL);
})

异常报告的限流

在大量异常发生时，可通过 throttle 方法控制报告数量。

use Illuminate\Support\Lottery;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    // 随机地每 1000 次报告 1 次
    $exceptions->throttle(function (Throwable $e) {
        return Lottery::odds(1, 1000);
    });
})

若想按每分钟次数限制，可使用 Limit。

use Illuminate\Broadcasting\BroadcastException;
use Illuminate\Cache\RateLimiting\Limit;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->throttle(function (Throwable $e) {
        if ($e instanceof BroadcastException) {
            return Limit::perMinute(300);
        }
    });
})

异常的渲染

渲染是指将异常转换为 HTTP 响应的处理。默认情况下 Laravel 会自动生成合适的响应，也可以自定义。

自定义渲染回调

向 render 方法传入闭包，将异常转换为响应。

use App\Exceptions\InvalidOrderException;
use Illuminate\Http\Request;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->render(function (InvalidOrderException $e, Request $request) {
        return response()->view('errors.invalid-order', status: 500);
    });
})

也可以覆盖内置异常（如 NotFoundHttpException）的渲染。若闭包不返回值，则使用默认渲染。

use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => 'Record not found.',
            ], 404);
        }
        // 返回 null 时会显示默认的 404 页面
    });
})

JSON / HTML 的自动判定

Laravel 会根据请求的 Accept 头自动判定返回 HTML 还是 JSON。若想自定义该判定逻辑，可使用 shouldRenderJsonWhen。

use Illuminate\Http\Request;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->shouldRenderJsonWhen(function (Request $request, Throwable $e) {
        if ($request->is('admin/*')) {
            return true; // 后台管理始终返回 JSON
        }

        return $request->expectsJson();
    });
})

对整个响应的定制

使用 respond 方法可以对生成的响应做进一步加工。

use Symfony\Component\HttpFoundation\Response;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->respond(function (Response $response) {
        if ($response->getStatusCode() === 419) {
            return back()->with([
                'message' => '页面已过期，请重试。',
            ]);
        }

        return $response;
    });
})

自定义异常类

可以在 app/Exceptions/ 目录中创建自己的异常类。若定义了 report() 和 render() 方法，即使不在 bootstrap/app.php 中配置也会被自动调用。

异常类的创建

创建异常类

php artisan make:exception InvalidOrderException

实现 report() 与 render()

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class InvalidOrderException extends Exception
{
    public function __construct(
        private readonly int $orderId,
        string $message = 'Invalid order.',
    ) {
        parent::__construct($message);
    }

    /**
     * 报告异常
     */
    public function report(): void
    {
        // 通知外部服务等
    }

    /**
     * 将异常转换为 HTTP 响应
     */
    public function render(Request $request): Response
    {
        return response()->view('errors.invalid-order', [
            'orderId' => $this->orderId,
        ], 422);
    }
}

report() 方法可以通过类型提示使用依赖注入。Laravel 的服务容器会自动解析。

`ShouldntReport` 接口

对于不需要报告的异常，可以实现 ShouldntReport 接口。实现该接口的异常将不会被报告。

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Contracts\Debug\ShouldntReport;

class PodcastProcessingException extends Exception implements ShouldntReport
{
    //
}

异常的抛出

`abort()` 辅助函数

可以在应用的任意位置产生 HTTP 错误响应。

// 404 Not Found
abort(404);

// 带消息
abort(403, '您没有执行此操作的权限。');

`abort_if()` / `abort_unless()`

条件式抛出异常的辅助函数。

// $condition 为 true 时中止
abort_if(! $user->isAdmin(), 403);

// $condition 为 false 时中止
abort_unless($user->hasPermission('edit'), 403, 'Permission denied.');

在控制器或中间件中做权限检查时很方便。也常与门（Gate）或策略（Policy）组合使用。

异常的全局控制

忽略特定异常

使用 dontReport 指定不报告的异常。渲染的自定义逻辑仍然生效。

use App\Exceptions\InvalidOrderException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontReport([
        InvalidOrderException::class,
    ]);
})

若希望条件性忽略，可向 dontReportWhen 传入闭包。

use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontReportWhen(function (Throwable $e) {
        return $e instanceof PodcastProcessingException &&
               $e->reason() === 'Subscription expired';
    });
})

Laravel 默认自动忽略 404 错误、CSRF 令牌无效（419）、来源不匹配（403）等部分异常。

恢复 Laravel 默认忽略的异常

要将默认忽略的异常恢复为报告对象，可使用 stopIgnoring。

use Symfony\Component\HttpKernel\Exception\HttpException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->stopIgnoring(HttpException::class);
})

HTTP 错误页

Laravel 允许按 HTTP 状态码定义自定义错误视图。

自定义错误视图的创建

在 resources/views/errors/ 目录中创建以状态码为文件名的 Blade 模板。

resources/
└── views/
    └── errors/
        ├── 404.blade.php
        ├── 403.blade.php
        └── 500.blade.php

视图内可以通过 $exception 变量访问错误信息。

{{-- resources/views/errors/404.blade.php --}}
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>页面未找到</title>
</head>
<body>
    <h1>404 - 页面未找到</h1>
    <p>{{ $exception->getMessage() }}</p>
    <a href="{{ url('/') }}">返回首页</a>
</body>
</html>

发布默认错误模板

若希望以 Laravel 标准错误页作为自定义起点，可通过 vendor:publish 获取。

php artisan vendor:publish --tag=laravel-errors

回退错误页

对于没有对应视图的状态码，可以创建 4xx.blade.php 和 5xx.blade.php 作为回退。

resources/
└── views/
    └── errors/
        ├── 4xx.blade.php  # 4xx 系列的回退
        └── 5xx.blade.php  # 5xx 系列的回退

对于 404、500、503，Laravel 提供了默认错误页。要自定义这些错误页，应创建单独的文件（如 404.blade.php），而不是回退文件。

实践示例：API 异常处理器

对于提供 API 的应用，异常需要始终以 JSON 形式返回。下面是在 bootstrap/app.php 中统一管理 API 错误的实现示例。

use Illuminate\Auth\AuthenticationException;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

->withExceptions(function (Exceptions $exceptions): void {
    // API 请求始终返回 JSON
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => '找不到资源。',
            ], 404);
        }
    });

    $exceptions->render(function (AuthenticationException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => '需要认证。',
            ], 401);
        }
    });

    $exceptions->render(function (ValidationException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => '校验错误。',
                'errors'  => $e->errors(),
            ], 422);
        }
    });
})

自定义 API 异常类的实现

创建 API 专用的基础异常类，可在各端点返回统一的错误响应。

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class ApiException extends Exception
{
    public function __construct(
        string $message = 'An error occurred.',
        private readonly int $statusCode = 500,
        private readonly array $errors = [],
    ) {
        parent::__construct($message);
    }

    public function render(Request $request): JsonResponse
    {
        $data = ['message' => $this->getMessage()];

        if (! empty($this->errors)) {
            $data['errors'] = $this->errors;
        }

        return response()->json($data, $this->statusCode);
    }
}

在控制器中的使用示例：

<?php

namespace App\Http\Controllers\Api;

use App\Exceptions\ApiException;
use App\Models\Order;

class OrderController extends Controller
{
    public function show(int $id): JsonResponse
    {
        $order = Order::find($id);

        if (! $order) {
            throw new ApiException('订单未找到。', 404);
        }

        if ($order->isCancelled()) {
            throw new ApiException('该订单已被取消。', 422);
        }

        return response()->json($order);
    }
}

小结

异常报告小结

方法	用途
`$exceptions->report()`	按异常类型注册自定义报告逻辑
`$exceptions->context()`	为所有异常日志附加公共信息
`context()` 方法	让异常类自身携带特有上下文
`report()` 辅助函数	不中断响应，仅报告异常
`dontReportDuplicates()`	防止同一实例的重复报告
`ShouldntReport` 接口	创建完全不报告的异常类

异常渲染小结

方法	用途
`$exceptions->render()`	按异常类型返回自定义响应
`render()` 方法	让异常类自身携带渲染逻辑
`shouldRenderJsonWhen()`	自定义 JSON/HTML 判定逻辑
`respond()`	对生成的响应做进一步加工

HTTP 错误页小结

只需创建 resources/views/errors/404.blade.php 等文件即可自动使用
可通过 $exception 变量访问错误详情
可通过 php artisan vendor:publish --tag=laravel-errors 获取默认模板
可通过 4xx.blade.php / 5xx.blade.php 定义回退页面

生产环境最佳实践

务必设置 APP_DEBUG=false，不向用户暴露堆栈跟踪
与 Sentry 或 Flare 等外部错误跟踪服务集成，统一管理错误
使用 throttle() 防止大量异常时日志溢出
在 API 端点保持一致的 JSON 错误响应格式

​概述

​异常处理流程

​调试设置

​异常的报告

​自定义报告回调

​report() 辅助函数

​防止重复报告

​全局日志上下文

​为异常类添加 context() 方法

​日志级别的更改

​异常报告的限流

​异常的渲染

​自定义渲染回调

​JSON / HTML 的自动判定

​对整个响应的定制

​自定义异常类

​异常类的创建

​ShouldntReport 接口

​异常的抛出

​abort() 辅助函数

​abort_if() / abort_unless()

​异常的全局控制

​忽略特定异常

​恢复 Laravel 默认忽略的异常

​HTTP 错误页

​自定义错误视图的创建

​发布默认错误模板

​回退错误页

​实践示例：API 异常处理器

​自定义 API 异常类的实现

​小结

概述

异常处理流程

调试设置

异常的报告

自定义报告回调

`report()` 辅助函数

防止重复报告

全局日志上下文

为异常类添加 `context()` 方法

日志级别的更改

异常报告的限流

异常的渲染

自定义渲染回调

JSON / HTML 的自动判定

对整个响应的定制

自定义异常类

异常类的创建

`ShouldntReport` 接口

异常的抛出

`abort()` 辅助函数

`abort_if()` / `abort_unless()`

异常的全局控制

忽略特定异常

恢复 Laravel 默认忽略的异常

HTTP 错误页

自定义错误视图的创建

发布默认错误模板

回退错误页

实践示例：API 异常处理器

自定义 API 异常类的实现

小结