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

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），可能被跳过拦截：

WebChat Voice Proxy

⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**

下载

• 通过 proxy_buffer_size 和 proxy_buffers 调整缓冲区，但更可靠的方式是：在后端响应头中显式设置 Content-Length，或让后端返回带 HTML body 的错误（哪怕只有 <p>Service unavailable</p>）
• 调试时可用 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 内

进阶：按状态码差异化处理

可为不同错误类型提供专属页面或逻辑：

• error_page 502 /502-maintenance.html;
• error_page 503 @maintenance;（配合 named location 实现内部跳转）
• error_page 404 = @not_found;（= 表示不修改响应状态码，仍返回 404）
• 在 @not_found 中可做日志记录、API 回调或动态渲染