在 nginx 中实现错误页面自定义重定向，核心方法是使用 error_page 指令将 http 状态码映射到特定的 uri 或外部 url。通过配置该指令，nginx 可以在遇到 404、500 等错误时，自动将请求内部重定向到指定的静态 html 文件或执行反向代理转发，从而展示友好的错误提示。
如何配置 error_page 指令进行内部重定向
要启用内部重定向，需在 server 或 location 块中使用 error_page 指定状态码和对应的处理路径。当请求触发指定状态码时，Nginx 会拦截响应并重新发起对目标路径的内部请求，最终返回目标路径的内容。
server {
listen 80;
server_name example.com;
# 定义错误页面映射
error_page 404 /custom_404.html;
error_page 500 502 503 504 /custom_50x.html;
location = /custom_404.html {
root /usr/share/nginx/html;
internal; # 仅允许内部重定向访问
}
location = /custom_50x.html {
root /usr/share/nginx/html;
internal;
}
location / {
proxy_pass http://backend;
}
}
上述配置中，error_page 404 /custom_404.html; 表示当发生 404 错误时，Nginx 会内部重定向到 /custom_404.html。注意，目标路径必须存在且可访问，通常配合 internal 指令防止用户直接通过 URL 访问错误页面文件，确保安全性。根目录 root 需指向包含这些 HTML 文件的实际路径。
如何将错误重定向到外部 URL 或不同服务器
除了内部重定向，error_page 还支持将错误重定向到外部绝对 URL。此时，Nginx 会向客户端发送一个 302 临时重定向响应，引导浏览器跳转到指定地址。这种方式适用于将错误流量分发到其他服务或 CDN 节点。
server {
listen 80;
server_name example.com;
# 重定向到外部 URL
error_page 404 https://www.example.com/error/404;
error_page 500 https://www.example.com/error/500;
location / {
proxy_pass http://backend;
}
}
在此配置中，error_page 404 https://www.example.com/error/404; 使用了完整的 HTTPS URL。当后端返回 404 时，Nginx 不会内部处理，而是直接向客户端返回 302 状态码及 Location 头，浏览器随后自动跳转。这种方式不依赖本地文件，适合分布式架构中的统一错误页管理。需注意，外部重定向会增加一次网络往返，可能影响用户体验，建议仅在必要时使用。
error_page 指令在不同 location 块中的优先级如何确定
当多个 location 块都定义了 error_page 时，Nginx 遵循“最精确匹配”原则确定生效规则。具体而言，请求首先匹配最具体的 location（如 = /exact 或最长前缀），若该块内定义了 error_page，则优先使用；否则向上回溯到父级 server 或更通用的 location 块。这种层级结构允许针对不同路径设置不同的错误处理策略。
server {
listen 80;
server_name example.com;
# 全局默认错误页
error_page 404 /global_404.html;
location /api/ {
# 仅对 /api/ 路径生效的 404 页
error_page 404 /api_404.html;
proxy_pass http://backend_api;
}
location /static/ {
# 静态资源路径无特殊错误页，继承全局
root /var/www/static;
}
location = /global_404.html {
root /usr/share/nginx/html;
internal;
}
location = /api_404.html {
root /usr/share/nginx/html;
internal;
}
}
在上述示例中，访问 /api/test 若触发 404，Nginx 会优先使用 location /api/ 块内定义的 /api_404.html；而访问 /static/image.png 若文件不存在，则因 location /static/ 未定义 error_page，会继承 server 级的 /global_404.html。这种机制确保了错误处理的灵活性和精确性，开发者可根据业务路径定制差异化体验。
