Nginx中proxy_intercept_errors实现统一错误页面拦截-Nginx-PHP中文网

proxy_intercept_errors 是 Nginx 代理中启用后端错误响应拦截的开关，需与 error_page 同作用域配合使用才能生效；仅开启该指令但未配置对应 error_page 时，Nginx 仍透传原始错误；它仅对状态码 ≥300 且含合法 HTTP 头部的响应生效，不处理 3xx 重定向或静态资源缺失等场景。

nginx中proxy_intercept_errors实现统一错误页面拦截

proxy_intercept_errors 是 Nginx 中用于接管后端服务返回的错误响应（如 404、500 等），并交由 Nginx 自身的 error_page 指令处理的关键指令。它本身不生成页面，而是开启“拦截开关”，让 Nginx 有机会用自定义错误页替代原始后端返回的内容。

启用拦截需同时满足两个条件

仅设置 proxy_intercept_errors on; 不起作用，必须配合 error_page 显式声明要处理的状态码：

在 location 或 server 块中启用：proxy_intercept_errors on;
在同一作用域内定义对应错误码的跳转，例如：error_page 404 /404.html; 或 error_page 500 502 503 504 /5xx.html;
确保目标错误页文件（如 /404.html）存在，且路径可被 Nginx 正确访问（建议放在 root 目录下）

常见误区：后端返回非标准状态码时拦截失效

该指令只对 HTTP 状态码 ≥ 300 的响应生效，但前提是响应体中包含完整、合法的 HTTP 头部（尤其是 Status 或 HTTP/1.x xxx）。若后端返回的是无状态行的纯文本或格式错乱响应，Nginx 可能无法识别为错误，导致不触发拦截。

aperture: the L402 aware reverse proxy

安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。

下载

调试方法：用 curl -v http://your-proxy/ 查看真实响应头和状态码
确保后端应用正确输出标准 HTTP 状态码，避免用 200 + 自定义 body 表示业务错误
若后端不可控，可结合 proxy_redirect 或 Lua 模块做更灵活判断

与 upstream 状态联动的进阶用法

当后端全部不可达（如全超时或拒绝连接），Nginx 默认返回 502/503/504，这些也受 proxy_intercept_errors 控制：

只要开启该指令，并配置了 error_page 502 /50x.html;，就能统一展示维护页
注意：500 类错误若由 Nginx 自身触发（如 rewrite 循环），不经过 proxy 流程，不受此指令影响
推荐将所有服务级错误（4xx/5xx）集中到一个兜底页：error_page 400 401 403 404 500 502 503 504 /error.html;