如何设置Nginx Error_page，实现ThinkPHP自定义错误页面？

本文共计786个文字，预计阅读时间需要4分钟。

如果您的ThinkPHP项目中配置了Nginx的`error_page`指令，但自定义错误页面未生效，很可能是因为Nginx拦截了错误响应。这可能导致PHP层的ThinkPHP路由逻辑（如`Route::miss()`）未能执行。

以下是解决此问题的步骤：

一、禁用Nginx对404的直接拦截

Nginx默认可能通过error_page 404或try_files规则提前返回404，使请求无法到达ThinkPHP。必须确保Nginx不主动截断404，而是交由PHP处理。

1、打开Nginx站点配置文件（如/etc/nginx/sites-enabled/your-site）。

2、查找并注释或删除形如error_page 404 /404.html;或error_page 404 = /404.html;的行。

立即学习“PHP免费学习笔记（深入）”；

3、检查location /块中的try_files指令，确保其末尾不是=404，而应为$uri $uri/ /index.php?$query_string;。

4、执行sudo nginx -t && sudo systemctl reload nginx重载配置。

二、启用ThinkPHP路由强制模式

ThinkPHP 6.x需开启url_route_must，否则URL解析可能绕过路由系统，导致404不触发miss()回调。

1、编辑config/app.php文件。

2、确认'url_route_must' => true,已取消注释且值为true。

3、保存后清空运行时缓存：php think clear。

三、在路由文件中注册Route::miss兜底响应

这是ThinkPHP 6中最可靠、最优先生效的404处理方式，它在所有路由规则匹配失败后触发，且支持视图渲染与状态码控制。

1、打开route/app.php文件。

2、在所有Route::get()、Route::post()等路由定义之后，添加以下代码：

Route::miss(function () { return response()->view('public/404', [], 404); });

3、确保public/404.html模板文件存在于resources/view/public/目录下。

4、若使用多应用模式，需在每个应用的route/app.php中重复配置。

四、配置Nginx将错误转发至PHP内部URI

当需兼顾Nginx级错误捕获与PHP端逻辑（如日志记录、邮件通知）时，应避免直接外部重定向，而改用内部URI由PHP脚本统一处理。

1、在Nginx server块中添加：error_page 404 /think-error-handler.php?code=404;。

2、新增location块以支持该PHP脚本：

location = /think-error-handler.php { internal; root /var/www/your-project; fastcgi_pass unix:/var/run/php/php-fpm.sock; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; }

3、创建public/think-error-handler.php文件，内容为：<?php http_response_code(404); include '../resources/view/public/404.html';。

五、验证Nginx是否传递真实HTTP状态码

若前端显示“成功”（200）但内容为404页面，说明Nginx修改了响应状态码，破坏SEO与客户端逻辑。

1、检查Nginx配置中是否存在error_page 404 =200 /404.html;类语句，该写法会强制覆盖状态码为200。

2、将其改为error_page 404 /404.html;（无等号），或彻底移除该行，交由PHP返回原生404。

3、使用curl -I http://yoursite.com/nonexistent验证响应头中HTTP/1.1 404 Not Found是否真实存在。