最常见原因是开启 proxy_intercept_errors on 后未配置对应状态码的 error_page，Nginx 会直接透传原始错误响应；必须同时满足：后端返回 ≥400 状态码、proxy_intercept_errors on、配置匹配该状态码的 error_page、后端响应体非空。
proxy_intercept_errors 开启后 error_page 为什么没生效
最常见的情况是：开了 proxy_intercept_errors on，但没配对应状态码的 error_page，Nginx 就会直接透传原始错误响应，不跳转、不替换、不拦截。这不是 bug，是设计行为。
必须同时满足四个条件才触发拦截：
- 后端返回状态码 ≥ 400（比如 404、502、503）
-
proxy_intercept_errors on已启用 - 配置了匹配该状态码的
error_page（如error_page 502 /50x.html） - 后端响应体非空（空响应体可能被忽略，尤其 FastAPI/Flask 默认 404 不带 body）
调试时用 curl -I http://your-proxy/missing 看响应状态码和 Content-Type 头是否来自你的静态页；再查 Nginx error log 是否出现 intercept 字样。
error_page 路径指向哪里才真正可访问
error_page 502 /50x.html 中的 /50x.html 是 URI 路径，不是文件系统路径。它必须能被某个 location 匹配并 serve 出来。
典型安全写法：
- 把静态页放在
/usr/share/nginx/html/下（Nginx 默认 root） - 显式声明
location = /50x.html { root /usr/share/nginx/html; internal; } -
internal很关键：防止用户直接请求/50x.html绕过代理逻辑 - 别写成
root /usr/share/nginx/html/50x.html;—— 这是错的，root后面只能是目录
如果用相对路径（如 error_page 502 /errors/50x.html），就得额外配一个 location /errors/ 块来映射到实际文件位置。
如何让 502/503/504 故障统一展示维护页
后端全部宕机、超时或拒绝连接时，Nginx 自身会生成 502/503/504 响应，这些也受 proxy_intercept_errors 控制 —— 只要开启 + 配了对应 error_page，就能捕获。
推荐兜底式写法：
location /api/ {
proxy_pass http://backend;
proxy_intercept_errors on;
error_page 400 401 403 404 500 502 503 504 /error.html;
}
location = /error.html {
root /usr/share/nginx/html;
internal;
}注意：500 类错误若由 Nginx 自身触发（如 rewrite 循环、内存不足），不走 proxy 流程，不受此控制，需单独靠全局 error_page 500 拦截。
为什么静态资源 404 不该用 proxy_intercept_errors 拦截
当 location 用于代理静态文件（如图片、JS/CSS），后端返回 404 时，若开启 proxy_intercept_errors，Nginx 会拦截并返回你配的 /404.html，但原始响应头（如 Content-Type: image/png）就丢了，浏览器可能无法正确渲染。
更合理做法是绕过 proxy 流程：
- 静态资源请求尽量由 Nginx 直接
try_files服务 - 失败再 fallback 到
error_page，不经过后端 - 例如：
location ~* \.(js|css|png|jpg)$ { try_files $uri @backend; }
真正需要 proxy_intercept_errors 的，是动态接口层（如 /api/），那里故障意味着服务不可用，该切维护页。
