如何为Laravel Jetstream + Inertia自定义Vue错误页面？

一、修正错误处理代码 #

原代码依赖parent::render()返回的响应状态码，可能因Laravel默认错误视图优先级更高导致失效。替换为直接捕获异常状态码的逻辑，确保Inertia响应优先返回：

<?php

namespace App\Exceptions;

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Inertia\Inertia;
use Throwable;

class Handler extends ExceptionHandler
{
    // ... 保留类中其他默认代码

    public function render($request, Throwable $e)
    {
        // 获取异常对应的HTTP状态码
        $statusCode = $this->isHttpException($e) ? $e->getStatusCode() : 500;

        // 针对指定状态码返回自定义Inertia错误页
        if (in_array($statusCode, [403, 404, 500, 503])) {
            return Inertia::render('Error', [
                'status' => $statusCode,
                'message' => $e->getMessage() ?: '发生了一个错误，请稍后重试。',
            ])
            ->toResponse($request)
            ->setStatusCode($statusCode);
        }

        // 处理419页面过期场景
        if ($statusCode === 419) {
            return back()->with([
                'message' => '页面已过期，请重试。',
            ]);
        }

        // 本地环境/其他异常保留默认处理逻辑
        return parent::render($request, $e);
    }
}

二、关键配置检查 #

1. 确保自定义Error组件存在
   在resources/js/Pages/目录下创建Error.vue，示例代码如下：

<template>
  <div class="min-h-screen flex items-center justify-center bg-gray-100">
    <div class="text-center">
      <h1 class="text-6xl font-bold text-gray-900 mb-4">{{ status }}</h1>
      <p class="text-xl text-gray-600 mb-8">{{ message }}</p>
      <button 
        @click="$inertia.visit('/')"
        class="px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition"
      >
        返回首页
      </button>
    </div>
  </div>
</template>

<script setup>
import { defineProps } from 'vue';

const props = defineProps({
  status: {
    type: Number,
    required: true,
  },
  message: {
    type: String,
    default: '页面访问出错',
  },
});
</script>

2. 删除Laravel默认错误视图
   如果resources/views/errors/目录下存在404.blade.php、500.blade.php等文件，Laravel会优先返回这些视图，需删除该目录下所有文件，确保Inertia响应生效。

3. 验证环境配置

• 生产环境需设置APP_DEBUG=false，避免暴露敏感错误信息；
• 本地测试时若需查看自定义错误页，可保留APP_DEBUG=true，无需额外限制环境判断。

4. 确认Inertia中间件配置
   检查app/Http/Kernel.php的web中间件组是否包含HandleInertiaRequests：

protected $middlewareGroups = [
    'web' => [
        // ... 其他中间件
        \App\Http\Middleware\HandleInertiaRequests::class,
    ],
];

三、测试验证 #

• 访问不存在的路由触发404错误，检查是否显示自定义Vue页面；
• 手动抛出500异常（如在控制器中写abort(500)），验证页面是否正常渲染；
• 测试419场景：长时间不操作后提交表单，确认提示信息正常显示。

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