Nginx 中 proxy_intercept_errors 配置错误页-Nginx-PHP中文网

proxy_intercept_errors本身不生成错误页，仅作拦截开关，必须与同作用域的error_page指令配对使用，且后端响应需为≥400状态码、响应体非空，三者缺一不可。

nginx 中 proxy_intercept_errors 配置错误页

proxy_intercept_errors 本身不生成错误页，它只是一个“拦截开关”——真正决定返回什么内容的，是必须和它配对使用的 error_page 指令。单独开启这个指令，页面照样透传原始错误，完全不起作用。

必须在同一 location 中成对配置

在代理请求的块里，proxy_intercept_errors on; 和 error_page 必须写在一起，缺一不可：

✅ 正确写法（同 location）：

location /api/ {
  proxy_pass http://backend;
  proxy_intercept_errors on;
  error_page 500 502 503 504 /error.html;
}

❌ 错误写法（作用域分离）：

location /api/ {
  proxy_pass http://backend;
  proxy_intercept_errors on;
}
error_page 500 /error.html;  # 在 server 级别 —— 不生效

错误页路径需有对应 internal location 支持

/error.html 是 URI 路径，不是文件系统路径。Nginx 需要能直接服务它，且不能被用户直访：

location = /error.html {
    internal;        # 关键：禁止 curl http://domain/error.html 直接访问
    root /usr/share/nginx/html;  # 文件实际位置：/usr/share/nginx/html/error.html
}

文件必须真实存在，且 Nginx 进程有读取权限
推荐 HTML 内联样式和脚本，避免二次请求失败
页面大小建议 ≥512 字节，防止浏览器忽略并显示默认错误页

常见状态码推荐覆盖范围

优先接管这几类最易暴露后端或影响体验的错误：

FastAPI Flask Proxy

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

下载

404（路径不存在）
500（后端内部异常）
502 / 503 / 504（网关、服务不可用、超时）

可统一指向一个兜底页：

error_page 404 500 502 503 504 /error.html;

如需隐藏原始错误码（比如避免 SEO 降权或前端自动重试），可强制改为 200：

error_page 502 503 504 =200 /error.html;

让拦截真正生效的三个硬性条件

Nginx 只有同时满足以下全部条件，才会放弃透传、执行 error_page：

后端响应状态码是标准的 ≥400 HTTP 错误码（如 502 Bad Gateway）
响应体非空（空 body 会被跳过；解决办法：后端至少返回 <p>Down</p>，或临时加 proxy_buffering off;）
proxy_intercept_errors on; 和对应 error_page 在同一作用域（location 或其父级 server）

不复杂但容易忽略