如何配置Nginx使ThinkPHP显示自定义404页面？

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

如果Nginx环境下运行ThinkPHP项目，访问不存在的路由时返回默认Nginx的404页面而非ThinkPHP自定义错误页面，可能是因为Nginx未将404请求交由ThinkPHP统一处理。根本原因在于Nginx将找不到文件的判断提前终止，未将请求转发至ThinkPHP。具体表现为Nginx直接返回404，未将请求底层转换为public/index.php处理。

一、启用Nginx error_page指令指向ThinkPHP入口

该方法利用Nginx的error_page机制，在发生404时内部重定向至index.php，使ThinkPHP的路由与异常处理逻辑生效，同时保留原始URL路径和查询参数。

1、在server块内添加error_page 404指令，指向/index.php，并携带原始URI信息：
error_page 404 /index.php?$request_uri;

2、确保location ~ \.php$块中已正确设置fastcgi_param SCRIPT_FILENAME与PATH_INFO：
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;

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

3、在public/index.php顶部临时加入调试语句，验证是否捕获到404请求：
if ($_SERVER['REDIRECT_STATUS'] == '404') {
  header('HTTP/1.1 404 Not Found');
  echo '

ThinkPHP 404 Handler Active

'; exit;
}

二、通过try_files兜底强制所有非静态请求进入index.php

此方案不依赖error_page，而是让Nginx在匹配不到真实文件或目录时，主动将请求转发给index.php，由ThinkPHP自身判断路由是否存在并抛出404异常，从而触发框架内置的异常渲染机制。

1、确认root指令指向项目public目录，例如：
root /var/www/myapp/public;

2、在location /块中配置完整try_files语句：
try_files $uri $uri/ /index.php?$query_string;

3、在location ~ \.php$块中确保包含以下关键参数：
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;

4、检查ThinkPHP配置文件config/app.php中'exception_handle' => \think\exception\Handle::class已启用，且APP_DEBUG关闭时能正常渲染404模板。

三、为二级目录部署单独配置404透传路径

当ThinkPHP部署在子路径（如/example/）时，Nginx必须显式传递子目录层级，否则$_SERVER['SCRIPT_NAME']缺失路径前缀，导致ThinkPHP无法识别入口位置，直接跳过路由解析而返回Nginx原生404。

1、使用location /example/ {}精确匹配子目录，而非仅location / {}：
location /example/ {
  alias /var/www/myapp/public/;
  try_files $uri $uri/ /example/index.php?$query_string;
}

2、在嵌套的PHP处理块中，显式设置SCRIPT_FILENAME为物理绝对路径：
fastcgi_param SCRIPT_FILENAME /var/www/myapp/public/index.php;

3、必须添加PATH_INFO支持，确保路由段被正确提取：
fastcgi_param PATH_INFO $fastcgi_path_info;

4、验证关键环境变量是否含子目录：
在public/index.php开头插入var_dump($_SERVER['SCRIPT_NAME'], $_SERVER['REQUEST_URI']); die();，确认输出中SCRIPT_NAME值为/example/index.php。

四、禁用Nginx默认404并交由FastCGI拦截后端错误

该方法适用于ThinkPHP应用本身抛出404异常（如RouteNotFoundException），需确保Nginx不提前截断，而是将PHP执行结果原样返回，由框架控制状态码与响应体。

1、在server块中启用fastcgi_intercept_errors指令：
fastcgi_intercept_errors on;

2、确保PHP-FPM配置中catch_workers_output = yes，避免错误被静默丢弃；

3、在location ~ \.php$块末尾添加error_page拦截：
error_page 404 = @tp404;
location @tp404 {
  rewrite ^(.*)$ /index.php?s=$1 last;
}

4、确认ThinkPHP中已注册全局404异常处理器，且config('app.exception_handle')指向可渲染HTML模板的类。