nginx的error_page指令是自定义错误响应的核心机制，通过将指定http状态码重定向到内部uri，再由对应location处理返回内容；需配合root/alias、internal及proxy_intercept_errors等确保生效。
Nginx 的 error_page 指令是实现自定义错误响应的核心机制，它不直接拦截错误，而是将指定的 HTTP 状态码重定向到一个内部 URI（或代理地址），再由该 URI 对应的 location 处理并返回内容。
基本语法与作用范围
error_page 可在 http、server 或 location 块中配置，优先级遵循 Nginx 配置继承规则：越靠近请求匹配位置的配置越生效。例如：
- 全局定义
error_page 404 /404.html;，适用于所有 server； - 在某个
location /api/中单独写error_page 502 /api-error.html;，则只对该路径下的 502 生效； - 若某 location 内未定义 error_page，会向上回溯到 server 或 http 块查找。
返回静态页面的典型写法
最常见需求是返回 HTML 错误页。需确保两个关键点：
- 目标文件存在且 Nginx 有读取权限（如
/usr/share/nginx/html/50x.html）； - 对应 location 必须能匹配该内部 URI，且不带外部重定向（即用
=或隐式内部跳转）。
示例配置：
error_page 404 /404.html;
location = /404.html {
root /usr/share/nginx/html;
internal; # 强制为内部跳转，禁止客户端直接访问
}
注意：internal 是安全必需项，否则用户可通过浏览器直接请求 /404.html 绕过正常逻辑。
代理到后端服务动态生成错误页
当需要根据错误上下文（如原始 URL、Host、请求头）动态生成响应时，可将 error_page 指向一个 proxy_pass location：
error_page 500 502 503 504 /error-handler;
location /error-handler {
proxy_pass http://backend/error;
proxy_set_header Host $host;
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Error-Status $status; # 需配合 map 指令提取真实状态码
}
此时需额外使用 map 提前捕获原始状态码（因为 $status 在 error_page 触发后已变为 404/500 等），例如：
map $status $real_status {
404 404;
500 500;
~^[5] 500; # 其他 5xx 统一映射为 500
}
注意事项与常见陷阱
几个容易出错的地方：
-
状态码不会自动继承：即使你配置了
error_page 404 /404.html，返回的响应状态码仍是 404；但如果你用proxy_pass转发，后端必须主动返回对应状态码，否则 Nginx 默认返回 200； - 避免循环：不要让 error_page 指向的 location 再次触发同类型错误（如 404 页面本身又 404）；
-
root 与 alias 区别：在
location = /404.html中推荐用root，因为alias对精确匹配的 URI 处理易出错； -
日志记录：Nginx 默认仍会记录原始错误（如 upstream timeout），可在 error_page 对应 location 中加
access_log off;避免干扰统计。
