Nginx中error_page拦截错误需满足三点：写在含proxy_pass的location或server块内、启用proxy_intercept_errors on、指向可访问的internal location；支持按路由定制降级页、命名location动态处理、等号控制返回状态码。

在 Nginx 的 location 块中利用 error_page 拦截特定路由的错误，关键不是“让 location 生成错误”，而是让它**捕获并接管由该 location 内部逻辑（如 proxy_pass、fastcgi_pass）产生的错误响应**。必须明确作用域、开启拦截开关，并精准匹配处理路径。

确保 error_page 生效的前提条件

以下三点缺一不可，否则会静默失效或触发“404 套娃”：

• 写在正确的层级：error_page 必须放在包含 proxy_pass 或 fastcgi_pass 的 location 块内，或其上级 server 块；不能放在 if 块或 http 块（除非全局统一处理）
• 显式开启拦截：在同级 location 中添加 proxy_intercept_errors on;（反向代理）或 fastcgi_intercept_errors on;（PHP 等），否则后端返回的 4xx/5xx 会被直接透传，不触发 error_page
• 目标文件或路径可访问：error_page 指向的 URI（如 /502.html）必须有对应 location = /502.html 块，且配置了 root 或 alias，指向真实存在的文件

按错误类型为不同路由定制拦截页

比如你有一个 API 路由 /api/v1/ 和一个静态资源路由 /assets/，希望它们出错时返回不同风格的降级页：

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

• 在 location /api/v1/ { ... } 内写：
  

  proxy_intercept_errors on;<br>error_page 502 503 504 /api-error.html;

• 在 location /assets/ { ... } 内写：
  

  proxy_intercept_errors on;<br>error_page 404 /missing-asset.html;

• 再统一定义两个内部 location：
  

  location = /api-error.html { root /usr/share/nginx/html; internal; }<br>location = /missing-asset.html { root /usr/share/nginx/html; internal; }

用命名 location 实现动态降级逻辑

当需要根据错误上下文做判断（比如只对 POST 请求降级、或记录错误日志后再返回），可用 @named_location 封装逻辑：

• 在目标 location 中写：
  

  proxy_intercept_errors on;<br>error_page 500 502 = @fallback_api;

• 定义命名 location：
  

  location @fallback_api {<br>  internal;<br>  proxy_pass http://backup_cluster;<br>  proxy_set_header X-Fallback-Reason "original_502";<br>}

• 注意：命名 location 不响应外部请求，只供内部跳转，必须加 internal

状态码是否覆盖要主动控制

error_page 行末尾的等号（=）决定最终返回给客户端的状态码：

• error_page 502 /502.html; → 返回 /502.html 内容，但状态码仍是 502（需在对应 location 中用 return 502 显式声明，否则默认 200）
• error_page 502 = /502.html; → 返回内容的同时，状态码被覆盖为 200
• error_page 502 =400 /502.html; → 显式指定返回 400 状态码