proxy_intercept_errors 指令用于拦截后端返回的 4xx/5xx 错误状态码并交由 nginx 自定义处理，需设为 on 并配合 error_page 指向降级页，支持按错误码差异化响应，结合 upstream 健康检查可实现主动降级，注意避免响应头冲突与静态资源加载失败。

proxy_intercept_errors 是 Nginx 的一个关键指令，它让 Nginx 能在后端服务返回特定 HTTP 错误状态（如 500、502、503、504）时，不直接透传错误给客户端，而是交由 Nginx 自己处理 —— 比如返回自定义的降级页面。这在后端宕机、超时或异常时，能显著提升用户体验和系统健壮性。

启用 proxy_intercept_errors 并配置基础降级逻辑

该指令默认为 off，需显式开启，并配合 error_page 使用：

• 在 location 块中设置 proxy_intercept_errors on;
• 用 error_page 500 502 503 504 /fallback.html; 指定哪些状态码触发降级，以及降级资源路径
• 确保 /fallback.html 文件存在于 Nginx 的 root 目录下（如 /usr/share/nginx/html/fallback.html）
• 注意：若后端返回的是 2xx/3xx，即使内容异常，也不会触发 intercept；它只响应明确的 4xx/5xx 状态码

支持不同错误码返回不同降级页

可以为不同故障类型提供更精准的提示，增强可维护性：

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

• error_page 502 504 /50x-maintenance.html;（网关超时、上游不可达）
• error_page 500 /50x-internal-error.html;（后端程序崩溃）
• error_page 503 /50x-overload.html;（主动限流或维护中）
• 每个页面可包含对应文案、联系方式或自动重试脚本，提升用户信任感

结合 upstream 和健康检查实现更智能的降级

单纯拦截错误码是被动响应，搭配 upstream 的主动探测可提前规避故障：

• 在 upstream 块中启用 health_check（需 Nginx Plus）或使用 check 模块（开源版常用）
• 配置 max_fails=2 fail_timeout=30s，使 Nginx 在连续失败后临时剔除异常节点
• 此时即使请求未走到后端，Nginx 也可能返回 503，仍会被 proxy_intercept_errors 捕获并降级
• 避免把用户请求打到已失联的服务上，降低错误率

注意事项与常见问题

实际部署中容易忽略几个关键点：

• proxy_intercept_errors 只对 代理响应的状态码 生效，不拦截 Nginx 自身错误（如 404、403），那些需单独用 error_page 处理
• 若后端返回了 Content-Length 或 Transfer-Encoding，而 Nginx 重写响应体，可能引发浏览器解析异常 —— 建议在降级 location 中显式清除：proxy_hide_header Content-Length; 和 chunked_transfer_encoding off;
• 静态降级页建议内联 CSS/JS，避免二次请求失败；也可用 alias 替代 root 精确映射路径
• 日志中可通过 $upstream_status 变量确认是否真实发生了上游错误，便于问题定位