如何配置 proxy_intercept_errors 实现后端服务异常时的自定义业务降级页面-Nginx-PHP中文网

Nginx 实现后端异常时返回自定义降级页需同时启用 proxy_intercept_errors on 并配合 error_page 指令绑定状态码，通过 internal 命名 location 安全提供静态页面，支持按路径或上游地址差异化降级。

如何配置 proxy_intercept_errors 实现后端服务异常时的自定义业务降级页面

要让 Nginx 在后端服务异常（如 502、503、504）时返回自定义业务降级页，关键不是单独打开 proxy_intercept_errors on，而是让它和 error_page 协同工作——前者是“开关”，后者才是“执行人”。配置错位或遗漏任一环节，页面都只会透传原始错误。

必须开启拦截并绑定具体状态码

proxy_intercept_errors 默认关闭，必须在 proxy_pass 所在的 location 块中显式启用，并紧接着用 error_page 指定哪些状态码触发降级：

在 location /api 或 location / 下添加：
proxy_intercept_errors on;
error_page 500 502 503 504 = @degrade;
注意等号 = 表示内部重定向，保留原始状态码；@degrade 是命名 location，不能被外部直接访问
不要写 error_page 502 /degrade.html 这类直接路径跳转，容易因 root 配置不一致导致 404

用 internal location 安全提供静态降级页

命名 location 必须设为 internal，并明确指定文件路径，确保降级页由 Nginx 直接返回，不经过后端：

Nginx Reverse Proxy

配置 Nginx 反向代理，实现域名绑定。用户说“绑定域名”“配置 Nginx”“反向代理”时触发，将域名绑定到指定 IP:端口。

下载

添加如下配置：

location @degrade {<br>  internal;<br>  root /usr/share/nginx/html;<br>  try_files /degrade.html =404;<br>}

root 要指向实际存放 degrade.html 的目录，不是 URI 前缀；try_files 提供兜底，避免因文件缺失返回 500
文件内容建议包含简明提示（如“服务暂时不可用，请稍后再试”）和基础样式，避免依赖外部资源

按业务路径差异化降级更实用

不是所有接口都需要同一张降级页。核心支付路径可返回“支付暂停”，而商品列表失败可展示缓存数据或空状态：

为关键路径单独配置：

location /api/order {<br>  proxy_pass http://order_backend;<br>  proxy_intercept_errors on;<br>  error_page 502 504 = @order_degrade;<br>}

配合 map 指令实现上游感知降级：

map $upstream_addr $degrade_page {<br>  ~10\.0\.1\.10:8080 "/degrade-core.html";<br>  ~10\.0\.1\.11:8080 "/degrade-user.html";<br>  default "/degrade-generic.html";<br>}

再在 location 中引用该变量做动态路由