Laravel 10中如何正确处理维护模式？原异常已移除

方法一：利用官方维护状态检测函数（最可靠） #

Laravel 10虽然移除了MaintenanceModeException，但保留了app()->isDownForMaintenance()辅助方法，能准确判断系统是否处于维护模式。你可以在异常处理器中针对HttpException做二次判断，返回自定义的API响应。

修改app/Exceptions/Handler.php，在render方法中添加逻辑：

public function render($request, Throwable $e)
{
    // 仅针对API请求和维护模式下的HttpException处理
    if ($request->is('api/*') && $e instanceof HttpException && app()->isDownForMaintenance()) {
        return response()->json([
            'code' => 503,
            'message' => '系统正在维护中，请稍后重试'
        ], 503);
    }

    return parent::render($request, $e);
}

或者用renderable回调（Laravel 8+支持），在register方法中添加：

public function register()
{
    $this->renderable(function (HttpException $e, $request) {
        if ($request->is('api/*') && app()->isDownForMaintenance()) {
            return response()->json([
                'status' => 'error',
                'msg' => '系统维护升级中，暂时无法提供服务'
            ], 503);
        }
    });
}

方法二：自定义维护模式的API专属响应 #

你可以直接为API请求定制维护模式的响应，无需依赖异常捕获。

方式1：通过事件监听

在app/Providers/AppServiceProvider.php的boot方法中监听维护模式启用事件：

use Illuminate\Foundation\Http\Events\MaintenanceModeEnabled;

public function boot()
{
    $this->app['events']->listen(MaintenanceModeEnabled::class, function () {
        if (request()->is('api/*')) {
            response()->json([
                'error_code' => 'MAINTENANCE',
                'error_msg' => '系统正在进行例行维护，预计30分钟后恢复'
            ], 503)->send();
            exit;
        }
    });
}

方式2：使用down命令指定API响应视图

创建一个API专用的503视图文件resources/views/errors/503-api.blade.php，内容为JSON：

{"code":503,"message":"系统维护中，请稍后再试"}

执行维护模式命令时指定该视图：

php artisan down --render="errors.503-api" --status=503

这样所有API请求都会返回这个自定义的JSON响应。

方法三：通过HttpException状态码+特征内容判断（备用） #

如果上述方法不适用，可通过HttpException的503状态码，结合默认响应的特征内容辅助判断（不如方法一可靠，仅作补充）：

public function render($request, Throwable $e)
{
    if ($e instanceof HttpException && $e->getStatusCode() === 503) {
        $defaultResponse = parent::render($request, $e);
        // 默认维护模式响应包含"Be right back"文本，可作为判断依据
        if (str_contains($defaultResponse->getContent(), 'Be right back')) {
            return response()->json([
                'message' => '系统维护中'
            ], 503);
        }
    }

    return parent::render($request, $e);
}

总结 #

优先选择方法一，app()->isDownForMaintenance()是官方提供的精准判断方法，不受异常类型变更影响，逻辑清晰且稳定。

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