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

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 可能无法识别为错误，导致不触发拦截。

Bailian Usage Proxy

阿里百炼大模型平台多人共享账号用量统计代理服务。解决公司共用账号时无法区分个人用量的问题。适用场景：1)部署用量统计代理；2)统计多人Token用量和调用次数；3)管理大模型API调用配额。

下载

• 调试方法：用 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;

静态资源错误不建议拦截

如果 location 用于代理静态文件（如图片、JS），通常不应开启 proxy_intercept_errors：

• 静态文件不存在时，后端（如 Tomcat）返回 404，Nginx 拦截后仍返回 404，但可能丢失原始响应头（如 Content-Type）
• 更合理做法是让静态请求直接由 Nginx try_files 处理，失败再 fallback 到 error_page
• 代理动态接口（如 /api/）才应开启该指令，保障用户体验一致性