直接修改 resources/views/errors/404.blade.php 和 500.blade.php 即可自定义错误页,Laravel 自动加载;但 APP_DEBUG=true 时 500 页被 Whoops 替代,需设为 false 才生效,404 页在调试模式下仍生效。

如何在 Laravel 中替换默认的 404 和 500 错误页面
直接改 resources/views/errors/404.blade.php 和 resources/views/errors/500.blade.php 就行。Laravel 会自动优先加载这两个文件,无需额外配置或注册。
注意:这两个文件必须放在 resources/views/errors/ 目录下,且文件名严格为 404.blade.php、500.blade.php(大小写敏感),否则不生效。
- 首次使用前可运行
php artisan vendor:publish --tag=laravel-errors生成默认模板(Laravel 8+ 默认已内置,但该命令能确保文件存在) - 如果目录不存在,手动创建
resources/views/errors并放入对应文件即可 - 模板中可正常使用 Blade 语法、
@include、@extends,比如继承你自己的layouts.app
为什么修改后 404 页面没变,但 500 页面正常?
常见原因是开发环境(APP_DEBUG=true)下,Laravel 会绕过 resources/views/errors/,直接显示 Whoops 错误详情页——这是设计行为,不是 bug。
- 404 是客户端错误,即使
APP_DEBUG=true也会走自定义视图(除非你触发的是路由未定义导致的“Whoops”式报错) - 500 是服务端异常,在
APP_DEBUG=true下**强制不走**500.blade.php,只显示调试堆栈;只有APP_DEBUG=false才会渲染它 - 验证方式:把
.env中的APP_DEBUG=false,然后用php artisan serve或 Nginx/Apache 访问一个真实会抛出异常的路由(如throw new \Exception('test');)
如何让错误页支持 CSS/JS 和布局复用?
直接在 404.blade.php 里用 @extends('layouts.app') 即可,和普通页面一样引用资源。但要注意:错误页是在异常上下文中渲染的,不能依赖可能已失效的服务或数据库连接。
- 避免在错误页中调用
Auth::user()、DB::table()等需要运行时环境的代码 - 静态资源路径建议用
{{ asset('css/error.css') }},别用url()或硬编码路径 - 如果用了 Vite,需确保
vite build后的产物已部署,且mix-manifest.json或vite-manifest.json可被读取(错误页不走 Webpack Mix 的重写逻辑) - 可添加简单内联样式保底,比如在
里写
想按 HTTP 状态码细分更多错误页(如 403、419、429)怎么办?
Laravel 支持任意标准状态码,只要命名规范:用三位数字作文件名,如 403.blade.php、419.blade.php(CSRF 失败)、429.blade.php(频率限制)。
- 这些页面同样放
resources/views/errors/下,无需任何注册 -
419和429在 Laravel 中有特殊处理逻辑,但最终仍会落到对应视图文件 - 注意
403页面不会自动触发——需在中间件或控制器中显式返回abort(403)或response('', 403) - 若想统一处理所有非 404/500 的错误,可建一个
error.blade.php作为兜底,但 Laravel 不会自动 fallback,需自行在App\Exceptions\Handler.php中 overriderender()方法
实际项目中最容易忽略的是 APP_DEBUG 对 500 页的屏蔽机制,以及错误页中意外调用已崩溃服务导致二次报错——这两点会让调试变得很迷惑。










