一、问题/场景描述

在部署或维护网站时，用户访问遇到404、500等错误时，默认的Nginx错误页面往往不友好且暴露服务器信息。开发者希望通过自定义Nginx配置报错页面，来提升用户体验和网站专业性，但在配置过程中常会遇到页面不生效、路径错误或权限问题等报错。

二、原因分析

Nginx配置报错页面失败的原因多样。最常见的是配置指令语法错误或放置位置不当，例如将error_page指令放在了不支持的作用域内。其次是自定义错误页面的文件路径不正确，或文件权限不足导致Nginx工作进程无法读取。此外，如果错误页面本身（如50x.html）需要后端（如PHP）动态生成，但相关代理或FastCGI配置有误，也会导致循环重定向或空白页。理解这些核心原因，是成功配置的关键。

三、详细解决步骤

以下步骤将引导您完成从创建自定义错误页面文件到正确配置Nginx的全过程。

步骤1：创建自定义错误页面文件

首先，在网站目录（例如/usr/share/nginx/html）下创建错误页面HTML文件。

sudo mkdir -p /usr/share/nginx/html/errors
sudo vim /usr/share/nginx/html/errors/404.html

在404.html文件中，编写简单的HTML内容。

404 - 您访问的页面不存在

同样地，创建50x.html用于服务器内部错误。

sudo vim /usr/share/nginx/html/errors/50x.html

确保Nginx进程用户（通常是nginx或www-data）有读取权限。

sudo chown -R nginx:nginx /usr/share/nginx/html/errors
sudo chmod -R 755 /usr/share/nginx/html/errors

步骤2：配置Nginx的error_page指令

打开目标网站的Nginx配置文件（通常在/etc/nginx/conf.d/或/etc/nginx/sites-available/）。在server {}块内添加error_page指令。

server {
    listen 80;
    server_name yourdomain.com;

    # 自定义错误页面配置
    error_page 404 /errors/404.html;
    error_page 500 502 503 504 /errors/50x.html;

    location / {
        root /usr/share/nginx/html;
        index index.html index.htm;
    }

    # 确保错误页面路径能被正确访问
    location /errors/ {
        internal; # 此指令表示该路径仅用于内部重定向，外部无法直接访问
        alias /usr/share/nginx/html/errors/;
    }
}

error_page后第一个参数是错误代码，第二个参数是响应该错误时使用的URI。

步骤3：测试配置与重载Nginx

在应用配置前，务必测试语法是否正确。

sudo nginx -t

如果输出syntax is ok和test is successful，则说明配置语法无误。然后重载Nginx使配置生效。

sudo systemctl reload nginx
# 或 sudo nginx -s reload

步骤4：验证与排查

访问一个不存在的URL（如http://yourdomain.com/nonexist）来触发404错误，检查是否显示自定义页面。如果未生效，请按以下顺序排查：

1. 检查Nginx错误日志：

sudo tail -f /var/log/nginx/error.log

2. 确认自定义页面文件路径在location /errors/块中配置正确，且权限足够。

3. 对于动态错误页（如由PHP处理），需确保error_page指令指向一个能由location ~ .php$处理的URI，并正确传递了参数。

error_page 500 /errors/50x.php;
location ~ /errors/50x.php$ {
    fastcgi_pass unix:/run/php/php8.1-fpm.sock;
    include fastcgi_params;
    # ... 其他fastcgi配置
}

四、注意事项

配置时需注意：error_page指令在http, server, location等块中均可使用，但要注意作用域优先级。自定义错误页面的文件大小不宜过大。若配置后仍显示默认页，可能是浏览器缓存，请强制刷新或清除缓存。对于代理后端服务的情况，需区分是Nginx错误还是后端应用错误。

五、适用环境

本配置方法适用于通过Nginx提供静态资源或作为反向代理服务器的Web服务环境。