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变量确认是否真实发生了上游错误，便于问题定位
