Nginx通过proxy_intercept_errors、error_page和location @name实现“拦截—重定向—兜底”三层错误处理逻辑,配合proxy_next_upstream提供前置重试容错。

Nginx 本身不主动修改后端返回的状态码,但可通过一组配套指令,对不同状态码触发差异化响应行为。核心在于“拦截—重定向—兜底”三层逻辑,而非简单转发。
proxy_intercept_errors 控制是否接管错误响应
默认情况下,Nginx 将 4xx/5xx 状态码原样透传给客户端。启用该指令后,它才开始检查响应状态码,并交由 error_page 指令处理:
- 必须配合 error_page 使用,单独开启无效果
- 仅对 Nginx 自身生成的错误(如 502/503/504)或后端返回的、被显式列入 error_page 的状态码生效
- 设置为 on 后,原本返回 502 的请求可能被替换成自定义 JSON 或静态页,但状态码仍保持 502(除非用 = 显式改写)
error_page 定义状态码到处理动作的映射
这是分支逻辑的调度中心,支持单个、多个或范围状态码绑定到指定 location 或 HTTP 状态码:
- 透传并跳转:error_page 404 /404.html; → 返回 302 跳转到 /404.html(状态码变为 302)
- 内部重写并返回:error_page 502 = @fallback; → 触发内部 location @fallback,状态码维持 502
- 强制改写状态码:error_page 503 =200 /health.json; → 返回 /health.json,且状态码强制为 200
- 可链式配置:error_page 502 503 504 = @api_down; error_page 404 = @not_found;
location @name 实现真正的分支执行体
@ 开头的命名 location 是内部跳转目标,不能被外部直接访问,适合封装兜底逻辑:
- 必须加 internal; 声明,否则会被外部请求绕过限制
- 可用 root + try_files 组合提供静态响应:try_files /down.json =404;
- 也可用 proxy_pass 转发到备用服务:proxy_pass http://backup_api;
- 支持变量和条件判断,例如根据 $scheme 决定返回 HTTP 还是 HTTPS 版本的降级页
proxy_next_upstream 针对网关级错误自动重试
这不是状态码分支,而是前置容错机制——在 upstream 层面对特定失败类型触发重试,避免走到 error_page 分支:
- 适用场景:后端多实例部署,某台因证书过期、宕机或超时返回 502/503
- 典型配置:proxy_next_upstream error timeout http_502 http_503;(注意不含 http_500)
- 需配合 proxy_next_upstream_tries 和 proxy_next_upstream_timeout 控制重试次数与总耗时
- 单点 upstream 下该配置无效,此时 error_page 是唯一可靠路径


















