Nginx 反向代理中怎么配置 proxy_intercept_errors 配合 error

proxy_intercept_errors 和 error_page 协同实现自定义错误页：前者开启后拦截后端返回的4xx/5xx状态码交由后者处理，后者定义错误响应内容与状态码重写规则，需配合 root/alias 和 internal 配置生效。

nginx 反向代理中怎么配置 proxy_intercept_errors 配合 error_page 重定向错误

proxy_intercept_errors 和 error_page 是 Nginx 中协同处理上游错误响应的两个关键指令，它们配合使用，能让客户端看到自定义错误页（如 502、503、504），而不是默认的 Nginx 错误提示或后端直接返回的原始错误内容。

什么是 `proxy_intercept_errors`

该指令控制 Nginx 是否拦截后端服务器返回的 HTTP 错误状态码（如 4xx/5xx），并交由 error_page 指令接管处理。
默认值是 off，即不拦截 —— 此时即使配置了 error_page 502 /502.html，Nginx 也不会触发它，而是直接把后端返回的 502 响应原样透传给客户端。

要启用拦截，必须显式设为 on，且通常放在 location 或 server 块中，作用于反向代理上下文。

location / {
    proxy_pass http://backend;
    proxy_intercept_errors on;  # 关键：开启拦截
    error_page 502 503 504 /custom_error.html;
}

注意：proxy_intercept_errors on 只对 后端返回的响应体状态码 生效（比如 Tomcat 崩了返回 502），对 Nginx 自身无法连接后端（如 connection refused）产生的 502 不生效 —— 那类错误由 error_page 502 直接捕获，无需依赖 proxy_intercept_errors。

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

下载

`error_page` 的行为要点

error_page 可以定义在 http、server 或 location 块，作用域越小优先级越高；

它本身不改变响应状态码，除非配合 =xxx 语法强制改写：

error_page 502 =503 /maintenance.html;  # 返回 503 状态码，内容是 maintenance.html

路径 /maintenance.html 是相对于 root 或 alias 指令指定的文档根目录；
若用 = 后跟状态码，Nginx 将以该状态码返回；若省略 =，则保持原始错误码（如 502）；
支持嵌套跳转，但需避免循环（例如 error_page 404 /404.html; 中 /404.html 本身又 404，会 fallback 到默认错误页）。

典型配置示例（带静态错误页）

http {
    # 全局 root，供 error_page 引用
    root /usr/share/nginx/html;

    upstream backend {
        server 127.0.0.1:8080;
        server 127.0.0.1:8081 backup;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            proxy_pass http://backend;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;

            # 启用拦截，让 error_page 处理后端返回的 5xx
            proxy_intercept_errors on;

            # 拦截并重定向到本地页面
            error_page 500 502 503 504 /5xx.html;
            error_page 404 /404.html;
        }

        # 显式声明错误页路径（可选，更清晰）
        location = /5xx.html {
            internal;  # 仅限内部跳转，禁止外部直接访问
            root /usr/share/nginx/html;
        }

        location = /404.html {
            internal;
        }
    }
}

✅ 效果：

后端挂掉返回 502 → Nginx 拦截 → 返回 /5xx.html 内容，状态码仍是 502（除非加 =503）；
请求一个不存在路径，后端返回 404 → 触发 error_page 404 → 返回 /404.html；
若 /5xx.html 文件本身缺失，Nginx 会 fallback 到内置 500 页面。

常见误区提醒

❌ 忘记 proxy_intercept_errors on：error_page 对后端返回的 5xx 无效；
❌ error_page 路径没配 root 或 alias：页面 404，最终显示空白或默认错误；
❌ 在 http 块写 error_page 却没在对应 server 或 location 中启用 proxy_intercept_errors：不生效；
❌ 使用 return 503 替代 error_page：它不走内容替换逻辑，无法加载自定义 HTML；
❌ 把 error_page 写在 upstream 块里：语法错误，Nginx 启动失败。