Laravel 11项目自定义异常处理失效问题求助

问题排查与解决方案 #

1. 调整异常处理的注册写法 #

Laravel 11通过bootstrap/app.php的->withExceptions()闭包配置异常处理，直接针对特定异常注册renderable可能因异常包装或优先级问题失效。改用全局捕获+类型判断的写法，确保自定义逻辑覆盖框架默认处理：

$exceptions->renderable(function (\Exception $e, \Illuminate\Http\Request $request) {
    // 处理Passport权限范围缺失异常
    if ($e instanceof \Laravel\Passport\Exceptions\MissingScopeException) {
        return response()->json([
            'success' => false,
            'error'   => '缺少必要的接口权限范围',
        ], 403);
    }

    // 处理API路由不存在异常
    if ($e instanceof \Symfony\Component\HttpKernel\Exception\NotFoundHttpException && $request->is('api/*')) {
        return response()->json([
            'success' => false,
            'error'   => '请求的API路由不存在',
        ], 404);
    }

    // 其他异常交给框架默认处理
    return null;
});

2. 关闭调试模式测试 #

当APP_DEBUG=true时，Laravel会优先返回调试错误页面，可能让你误以为自定义逻辑未生效。临时将.env中的APP_DEBUG改为false后重新测试。

3. 清除应用缓存 #

Laravel 11的配置缓存可能导致异常处理逻辑未更新，执行以下命令清除缓存：

php artisan optimize:clear

4. 延迟注册异常处理（备选方案） #

如果Passport自身的异常处理逻辑先于你的代码注册，可将自定义逻辑移至App\Providers\AppServiceProvider的boot方法（该方法在所有服务提供者注册后执行）：

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Foundation\Exceptions\Handler;
use Laravel\Passport\Exceptions\MissingScopeException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        $exceptionHandler = $this->app->make(Handler::class);

        // 注册Passport异常处理
        $exceptionHandler->renderable(function (MissingScopeException $e, $request) {
            return response()->json([
                'success' => false,
                'error'   => '缺少必要的接口权限范围',
            ], 403);
        });

        // 注册API404异常处理
        $exceptionHandler->renderable(function (NotFoundHttpException $e, $request) {
            if ($request->is('api/*')) {
                return response()->json([
                    'success' => false,
                    'error'   => '请求的API路由不存在',
                ], 404);
            }
        });
    }
}

5. 验证异常实例类型 #

确保抛出的异常确实是目标类，而非被框架包装后的其他异常。可在测试代码中临时打印异常类名确认：

try {
    throw new \Laravel\Passport\Exceptions\MissingScopeException();
} catch (\Exception $e) {
    dd(get_class($e)); // 输出异常类名，确认是否为目标类
}

内容的提问来源于stack exchange，提问作者Kevin Dijkstra