Nginx自定义错误页面无法正常生效问题排查

我之前也碰到过一模一样的问题，折腾了好一阵子才搞定，给你几个排查方向，应该能解决你的问题：

• 先确认错误页面的路径绝对正确
  别依赖相对路径！不管是在服务器配置里还是PHP代码里，优先用绝对路径试试。比如你的错误页面存在/var/www/html/error/404.php，直接写全路径，别用error/404.php或者./404.php这种相对路径。如果是在PHP里调用，可以用__DIR__来拼接路径，避免路径解析错误：

  $errorPage = __DIR__ . '/error/404.php';
  include($errorPage);
  

  另外，先直接在浏览器访问这个错误页面的完整URL，看看能不能正常打开。如果直接访问都空白，那问题出在页面本身（比如语法错误），不是配置的锅。

• 检查服务器配置的错误页面指向
  不同服务器的配置逻辑不一样，别搞混了：

  • 如果你用Apache：确保httpd.conf或者网站根目录下的.htaccess配置正确，比如：

    ErrorDocument 404 /error/404.php
    

    这里的/error/404.php是相对于网站根目录的路径，比如网站根是/var/www/html，那对应的物理路径就是/var/www/html/error/404.php，一定要保证文件存在。另外，Apache需要允许.htaccess生效，得在httpd.conf里把对应目录的AllowOverride设为All。
  • 如果你用Nginx：配置要注意关联PHP解析，不然会直接下载文件或者显示空白：

    error_page 404 /error/404.php;
    location = /error/404.php {
        root /var/www/html; # 你的网站根目录
        fastcgi_pass unix:/run/php/php7.4-fpm.sock; # 换成你的PHP-FPM套接字路径
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
    

    这里的fastcgi_param配置非常关键，少了它PHP无法正确解析脚本，会导致空白页面。

• 检查文件权限与所有者
  服务器进程要有读取错误页面的权限，不然会返回“File not found”或者空白。一般来说，把文件权限设为644，所在文件夹权限设为755，然后把所有者改成服务器运行的用户（比如Apache的www-data，Nginx的nginx）：

  chown www-data:www-data /var/www/html/error/404.php
  chmod 644 /var/www/html/error/404.php
  

• 开启PHP错误提示排查页面本身问题
  有时候空白页面是因为PHP脚本有语法错误，但错误被隐藏了。可以临时开启错误提示，找到问题所在：

  • 在php.ini里修改：

    display_errors = On
    error_reporting = E_ALL
    

  • 或者直接在错误页面的最开头添加：

    ini_set('display_errors', 1);
    ini_set('error_reporting', E_ALL);
    

  这样如果页面有语法错误，就能看到具体的报错信息，不会再显示空白了。

• 重启服务器清除缓存
  有时候服务器会缓存旧的配置，改完配置后一定要重启服务器生效：

  • Apache：systemctl restart apache2
  • Nginx：systemctl restart nginx
  • PHP-FPM：systemctl restart php7.4-fpm（换成你的PHP版本）

最后别忘了，测试的时候要对应你配置的错误码，比如你只配置了404的错误页面，却去测试500错误，那肯定不会生效哦！

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