如何配置proxy_intercept_errors统一接管后端错误-Nginx-PHP中文网

proxy_intercept_errors 用于拦截后端4xx/5xx错误响应并触发error_page自定义处理，需配合error_page显式声明状态码，且响应体≥512字节才生效，避免循环重定向并支持按状态码差异化处理。

如何配置proxy_intercept_errors统一接管后端错误

proxy_intercept_errors 是 Nginx 的一个关键指令，用于开启错误响应体的拦截与重写能力。它本身不接管错误，而是配合 error_page 指令，让 Nginx 在收到后端返回 4xx/5xx 状态码（且响应体非空）时，放弃直接透传原始错误页，转而触发自定义错误处理流程——这才是“统一接管”的实质。

启用拦截并绑定错误页

仅设置 proxy_intercept_errors on; 不会生效，必须搭配 error_page 显式声明要接管的状态码：

在 location 或 server 块中添加：
proxy_intercept_errors on;
紧接着定义接管逻辑，例如：
error_page 404 500 502 503 504 /custom_error.html;
确保 /custom_error.html 文件存在于 Nginx 的 root 目录下，或用 alias 明确路径

注意响应体大小限制

Nginx 默认只拦截响应体长度 ≥ 512 字节的错误响应。若后端返回精简错误（如纯文本 502 Bad Gateway），可能被跳过拦截：

通过 proxy_buffer_size 和 proxy_buffers 调整缓冲区，但更可靠的方式是：在后端响应头中显式设置 Content-Length，或让后端返回带 HTML body 的错误（哪怕只有 Service unavailable WebChat Voice Proxy ⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...** 下载）
调试时可用 curl -i 查看后端真实响应头和 body 长度

避免循环与覆盖默认行为

常见误配会导致接管失效或无限重定向：

不要在 error_page 中指向同一 location（例如 error_page 502 /;），否则可能触发循环
若使用 return 或 rewrite 替代静态文件，需确认状态码是否被正确继承；建议优先用 error_page 502 =502 /fallback.html; 显式保留状态码
全局 error_page（在 http 块）会被 server/location 中的同级定义覆盖，接管逻辑应尽量放在靠近 proxy_pass 的 location 内