proxy_intercept_errors 是 Nginx 拦截后端错误响应的开关，需配合 error_page 使用才能实现统一错误处理，仅开启本身无实际效果。
proxy_intercept_errors 是 Nginx 的一个关键指令，它本身并不“统一处理路径错误”，而是开启对后端返回的 HTTP 错误响应（如 404、500、502 等）的拦截能力——只有开启后，Nginx 才能用 error_page 指令接管这些响应，进而实现自定义错误页、重定向或内部跳转等统一处理逻辑。
必须配合 error_page 才能生效
单独设置 proxy_intercept_errors on; 不会产生任何实际效果。它只是“放行开关”：告诉 Nginx “别直接把后端的 404 响应透传给客户端，先留给我处理”。真正执行处理的是后续的 error_page 指令。例如：
proxy_intercept_errors on;-
error_page 404 /custom-404.html;→ 返回静态页 -
error_page 404 = @fallback;→ 内部重定向到命名 location -
error_page 404 =302 /search?q=$uri;→ 302 重定向到搜索页
只拦截错误状态码，不识别“路径语义”
Nginx 不解析后端返回内容里的路径信息（比如 HTML 中的“页面未找到”文字或 JSON 中的 "error": "path not found"）。它只看响应的 HTTP 状态码。因此所谓“路径错误”，需满足两个前提：
- 后端服务在路径不存在时，明确返回 404（或 400/500 等可拦截状态码），而非一律返回 200 + 自定义错误体
- 确保后端没有自行输出
Content-Length: 0或Connection: close等干扰 Nginx 缓存和拦截的响应头
常见统一处理方式（以 404 为例）
利用 error_page 可灵活适配不同场景：
-
返回静态错误页：
error_page 404 /err/404.html;，需提前将页面放在 root 目录下 -
内部重试其他后端：
error_page 404 @try-api-v2;，再定义location @try-api-v2 { proxy_pass http://api_v2; } -
记录并透传原始路径：
error_page 404 = @log_and_redirect;，在@log_and_redirect中用log_subrequest on;记日志，并用rewrite ^(.*)$ /notfound?path=$1 break;转发 -
JSON 格式 API 错误响应：
error_page 404 =200 /api-error.json;，配合add_header Content-Type application/json;
注意作用域与继承关系
proxy_intercept_errors 默认为 off，且不继承。如果在 http 块启用，子 server 或 location 中仍需显式开启才能生效。更稳妥的做法是写在具体需要拦截的 location 块内：
location /api/ {
proxy_pass http://backend;
proxy_intercept_errors on;
error_page 404 = @handle-api-404;
}
location @handle-api-404 {
internal;
# 返回统一 JSON 错误
return 200 '{"code":404,"msg":"Resource not found"}';
add_header Content-Type application/json;
}
