proxy_intercept_errors 必须与同作用域的 error_page 配合才生效，仅在含 proxy_pass 的 location 中起作用；http 块配置不继承，error_page 不可继承，需在 server 或 location 级显式配置。
不能在 http 块统一开启 proxy_intercept_errors on 并指望它自动接管所有后端错误响应——这是常见误解。该指令本身不生效，必须与同作用域的 error_page 指令配合，且仅对当前 location 内的 proxy_pass 流量起作用。
为什么 http 块全局配置会失效
proxy_intercept_errors 的作用域虽支持 http、server、location，但它的拦截行为只发生在实际执行 proxy_pass 的 location 中。即使你在 http 块写了 proxy_intercept_errors on，若某个 location 里没配 error_page，Nginx 仍会透传原始错误（比如 502/504）；更关键的是，error_page 指令**不可继承**，http 块中定义的 error_page 对子 server 或 location 无效。
真正可行的“统一接管”方案：按 server 或 location 分层控制
所谓“统一”，是指策略一致、复用性强，而非靠单点配置覆盖全部。推荐以下结构化做法：
- 在每个
server块顶部统一启用：proxy_intercept_errors on; - 为共性错误（如 502/504/404）在
server级配通用error_page：error_page 502 504 /50x.html;error_page 404 /404.html; - 为需要差异化处理的路径（如
/api/），在对应location中覆盖重写：location /api/ {proxy_pass http://api_upstream;error_page 502 504 = @api_fallback;} - 确保降级页文件存在，且有专用
location服务它：location = /50x.html {root /usr/share/nginx/html;internal;}
避免踩坑的关键细节
以下三点不注意，就容易看似配了却依然透传错误：
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
-
error_page 的 URI 必须可路由：例如写
error_page 502 /50x.html，就得有location = /50x.html块来响应这个请求，否则 Nginx 会返回 404 或 500 -
internal 是安全底线：所有降级页的
location都要加internal，防止用户直接访问/50x.html绕过业务逻辑 -
文件权限和路径要验证：Nginx worker 进程需有读取
/usr/share/nginx/html/50x.html的权限；文件大小建议 >512 字节，避免某些浏览器（如旧版 IE）忽略自定义页而显示默认错误
进阶：用 map 实现跨 location 的语义化降级
如果多个 upstream 返回不同服务标识（如响应头 X-Service-Name: user），可在 http 块定义映射，再在 server 或 location 中复用：
map $upstream_http_x_service_name $fallback_path { "user" "/user-offline.html"; "order" "/order-limited.html"; default "/system-busy.html";}
然后在任意 location 中：error_page 502 504 = $fallback_path;
配合 location ~ ^/(user-offline|order-limited|system-busy)\.html$ { root /usr/share/nginx/html; internal; }
