proxy_intercept_errors 用于让 Nginx 拦截后端返回的 4xx/5xx 错误并交由 error_page 处理自定义响应；需同时启用 proxy_intercept_errors on 并配置匹配的状态码 error_page，且响应体大小不超过 proxy_buffer_size 与 proxy_buffers 总和。

nginx 中怎么配置 proxy_intercept_errors 拦截后端错误页面

proxy_intercept_errors 的作用是让 Nginx 在后端返回 4xx 或 5xx 错误响应时，不直接把原始错误页透传给客户端，而是由 Nginx 自己根据 error_page 指令来接管并返回自定义错误页（比如统一的 50x 页面或跳转逻辑）。

启用拦截需同时满足两个条件

仅设置 proxy_intercept_errors on; 是不够的，必须配合 error_page 才生效：

Nginx 必须能识别后端响应的状态码（如 502、503、504），且该状态码在 error_page 中有对应处理
后端响应体大小不能超过 proxy_buffer_size + proxy_buffers 总和，否则 Nginx 无法完整读取响应头和体，可能跳过拦截

基础配置示例

以下是一个典型的反向代理中拦截 502/503/504 并返回本地静态页的写法：

location / {
    proxy_pass http://backend;
    proxy_intercept_errors on;
<pre class="brush:php;toolbar:false;"># 拦截指定错误码，交给本地 /50x.html 处理
error_page 502 503 504 /50x.html;

# 确保 Nginx 能缓存住错误响应头+少量内容
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;

}

提供自定义错误页的 location

location = /50x.html { root /usr/share/nginx/html; internal; # 仅限内部 error_page 调用，禁止外部直接访问 }

常见误区与注意事项

不要漏掉 internal：用于 error_page 的 location 必须加 internal，否则用户可通过 URL 直接请求 /50x.html，暴露错误页路径或绕过业务逻辑
状态码要匹配准确：如果后端返回的是 500，但只写了 error_page 502 503 504 ...，则不会触发拦截，Nginx 会原样返回 500 页面
不拦截 3xx 和 2xx 响应：该指令只对 4xx/5xx 生效；重定向（301/302）和成功响应（200）始终透传
与 proxy_redirect 无关：它控制的是响应头中的 Location 重写，不影响错误拦截逻辑

进阶用法：跳转到上游健康检查页或 API

除了返回静态页，也可以用 error_page 触发内部重定向到另一个 upstream 或返回 JSON：

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

error_page 502 503 504 @fallback;
<p>location @fallback {</p><h1>返回统一 JSON 错误</h1><pre class="brush:php;toolbar:false;">return 503 '{"code":503,"message":"Service unavailable"}';
add_header Content-Type "application/json";

}

这样前端可统一解析 JSON，无需依赖 HTML 解析逻辑。