proxy_intercept_errors 是 Nginx 后端故障优雅降级的前提开关，需配合 error_page 指令使用：开启后拦截 ≥300 状态码（如 502/503/504），再由 error_page 重定向至静态页、备用后端或自定义响应。
proxy_intercept_errors 是 Nginx 实现后端故障时优雅降级的关键开关，但它本身不直接“降级”，而是配合 error_page 指令，将上游返回的错误响应（如 502/503/504）拦截并重定向到本地资源或备用服务。
开启拦截是前提：必须显式启用
默认情况下，Nginx 遇到上游错误（比如 Tomcat 崩溃、PHP-FPM 超时）会直接把原始错误页（如 “502 Bad Gateway”）透传给客户端。要接管这个过程，需在 location 或 server 块中设置：
proxy_intercept_errors on;
注意：该指令仅对 proxy_pass 生效，且只拦截 HTTP 状态码 ≥ 300 的响应（常见如 404、500、502–504），不拦截 2xx 或 3xx 响应。
拦截后做什么？靠 error_page 绑定处理逻辑
单独开启 proxy_intercept_errors 没有意义——它只是“允许拦截”，真正实现降级的是 error_page。典型用法：
aperture: the L402 aware reverse proxy
下载
安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。
- 返回静态维护页：
error_page 502 503 504 /maintenance.html;
配合location = /maintenance.html { root /usr/share/nginx/html; } - 回退到备用后端：
error_page 502 503 504 @fallback;
location @fallback { proxy_pass http://backup_backend; } - 返回自定义 JSON 提示（适合 API 场景）：
error_page 502 503 504 /api-down.json;<br> location = /api-down.json {<br> default_type application/json;<br> return 503 '{"status":"unavailable","message":"Service temporarily down"}';<br> }
关键细节：避免常见陷阱
-
作用域必须匹配：如果
proxy_pass在location /api/中，那么proxy_intercept_errors和error_page也必须写在同一个location块内，否则不生效 -
error_page 的路径是内部 URI：如
error_page 502 /down.html中的/down.html不是文件路径，而是 Nginx 内部重写的目标 URI，需另配location处理它 -
不要忽略 upstream 状态码范围：若上游返回 404，而你只写了
error_page 502 503，则 404 仍会透传；按需补全需要拦截的状态码 -
与 fastcgi_intercept_errors 类似但不通用：如果是 FastCGI（如 PHP），需用
fastcgi_intercept_errors on;，不能混用
进阶：结合 try_files 实现多级兜底
对于更复杂的降级策略（如先查缓存页，再查静态页，最后返回 JSON），可组合使用：
location / {
proxy_pass http://origin;
proxy_intercept_errors on;
error_page 502 503 504 @fallback;
<h1>兜底 location</h1><p>location @fallback {</p><h1>尝试读取缓存好的 HTML 页面（如由定时任务生成）</h1><pre class='brush:php;toolbar:false;'>try_files /cache/maintenance.html /static/maintenance.html @json_fallback;}
location @json_fallback { default_type application/json; return 503 '{"code":503,"msg":"Service unavailable"}'; } }
这种方式让降级路径更灵活，也便于运维快速切换状态（只需更新对应文件）。
