proxy_intercept_errors 本身不拦截或替换页面，仅作为开关启用对后端4xx/5xx状态码的接管能力；必须与同作用域的error_page指令配合，且响应体非空时才生效。

proxy_intercept_errors 的作用不是“拦截”错误，而是让 Nginx 在后端返回 4xx 或 5xx 状态码时，**放弃直接透传响应体，转而尝试查找并返回本地定义的错误页面（如 error_page 指令配置的页面）**。

它只对 HTTP 状态码起作用

该指令仅影响后端返回的响应状态码（如 404、502、503），不处理后端返回的异常内容（如 JSON 错误信息、HTML 堆栈跟踪）、超时、连接拒绝等非标准 HTTP 响应。如果后端返回的是 200 状态码但内容是错误信息（比如 {"error":"invalid token"}），proxy_intercept_errors 完全不会触发。

• 开启后：Nginx 收到 502 → 不把后端的“Bad Gateway”页面原样返回，而是检查是否有 error_page 502 /502.html，有则返回该本地文件
• 关闭（默认）：Nginx 直接将后端的原始响应（含状态码和响应体）透传给客户端

必须配合 error_page 才有意义

单独设置 proxy_intercept_errors on; 没有效果。它只是“开关”，真正接管错误响应的是 error_page 指令：

FastAPI Flask Proxy

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

下载

• proxy_intercept_errors on; 启用拦截机制
• error_page 500 502 503 504 /error.html; 定义哪些状态码映射到哪个本地资源
• location = /error.html { internal; }（推荐）确保该路径只能由 error_page 内部跳转访问，不能被用户直接请求

注意作用域和继承关系

该指令在 http、server、location 块中均可配置，但遵循 Nginx 配置继承规则：子块会覆盖父块设置。常见误区是全局开了 proxy_intercept_errors on;，但在某个 location 里没配 error_page，结果该 location 下的错误仍被透传 —— 因为没有定义“接管方式”。

• 建议在具体需要定制错误页的 location 块内统一配置：proxy_intercept_errors on; + 对应 error_page
• 避免在 http 块盲目开启，否则所有 proxy_pass 都可能意外丢失后端错误详情（调试困难）

调试技巧：临时关闭来确认问题来源

当发现错误页没生效，先检查：

• 后端实际返回的状态码是否真的是 4xx/5xx（用 curl -I 或浏览器开发者工具 Network 标签查看）
• Nginx 配置中是否同时存在 proxy_intercept_errors on; 和匹配该状态码的 error_page
• 对应 error_page 路径下的文件是否存在、权限是否可读
• 日志中是否有 upstream sent too big header 等导致 Nginx 自身生成 502 的情况（这类错误也会被拦截）