Webman自定义错误页面设置_Webman 404与500界面美化【技巧】

林译川

2026-09-08 • 👁 0人浏览过

Webman的404必须用Route::fallback()处理、500必须重写Handler::render()；二者均需手动设置withStatus()确保状态码正确，且模板资源路径与Nginx静态配置需匹配，否则状态码错误或样式丢失。 Webman 的 404 和 500 页面不能靠 Nginx

error_page

配置“一劳永逸”，必须分层处理：404 必须走

Route::fallback()

，500 必须重写

Handler::render()

；否则页面能显示，但状态码大概率是 200，SEO 和调试全失效。 Route::fallback() 是唯一可靠的 404 入口 Webman 不识别 Laravel 风格的

resources/views/errors/404.blade.php

，也不响应 Nginx 的

error_page 404

—— 后者只在请求连

index.php

都没到达时才触发（比如直接访问

/missing.css

）。真正的 404 是“路由未命中”，属于 PHP 层逻辑，只能由

Route::fallback()

捕获。必须把

Route::fallback()

放在

config/route.php

最末尾，否则前置路由会提前拦截回调里要调用

$request->expectsJson()

区分 AJAX 请求，JSON 返回

json(['code'=>404,'msg'=>'not found'])

，HTML 请求返回

view('404')->withStatus(404)

模板路径写

view('404')

即可，Webman 默认从

app/view/404.html

加载，别放错目录或加后缀别在 fallback 里

throw

新异常，这会让流程跳进 500 处理器，而不是继续走 404 500 页面必须重写 Handler::render() 500 错误本质是 PHP 运行崩溃（语法错误、内存超限、未捕获异常），Nginx 的

error_page 500

只在 PHP-FPM 成功返回 500 状态头时才生效；一旦 PHP 进程彻底挂掉，Nginx 只能吐原始错误文本。所以你得自己写

app/exception/Handler.php

，并在

config/exception.php

中注册：

return ['' => \app\exception\Handler::class];

render()

方法里必须手动调用

->withStatus(500)

，否则响应头仍是 200 模板中可用

$exception

变量，但生产环境别直接输出

$exception->getTraceAsString()

，有信息泄露风险如果用了中间件（如鉴权）抛出异常，确保它没提前

try/catch

并吞掉异常，否则根本进不到这个

render()

app/view/500.html

里别调用

asset()

或

url()

辅助函数——异常发生时这些服务可能已不可用静态资源加载失败会连累错误页样式即使你写了

withStatus(404)

，404 页面本身也可能加载不了 CSS/JS —— 这不是 Webman 的问题，而是 Nginx/Apache 的静态资源

location

规则没配好。比如你的

404.html

引用了

/css/app.css

，但 Nginx 没把该路径转发给 PHP，就会触发二次 404，导致样式丢失。检查 Nginx 配置中

location ~* \.(css|js|png|jpg|gif|ico)$

是否存在且权限正确用

curl -I http://localhost/css/app.css

验证静态资源是否返回 200，而不是 404 错误页里的资源引用尽量用绝对路径（如

/css/404.css

），避免相对路径解析歧义别在

404.html

里写

header("Location: /")

或 JS 跳转，这会让状态码变成 302，搜索引擎当真最容易被忽略的是：404 模板和 500 模板自身出错会二次崩溃。比如

404.html

里引用了不存在的

$error

变量，或者

500.html

里调用了已销毁的服务，结果 fallback 到 Nginx 默认页，连自定义内容都看不到。

相关文章