Nginx 中怎么使用 proxy_pass 转发时处理后端返回的自定义错误码-Nginx-PHP中文网

nginx需启用proxy_intercept_errors on并配合error_page映射至internal location，才能统一处理后端自定义错误码；通过return $status或指定状态码返回标准化响应体，并可隐藏/添加响应头、记录日志验证。

nginx 中怎么使用 proxy_pass 转发时处理后端返回的自定义错误码

在 Nginx 中使用 proxy_pass 时，后端返回的自定义错误码（如 499、503、422 或业务自定义的 4xx/5xx）默认会被透传给客户端。若需统一处理（比如重写响应体、跳转页面、记录日志或返回标准化 JSON），需结合 proxy_intercept_errors、error_page 和可选的 proxy_hide_header/add_header 等指令实现。

启用错误拦截并绑定自定义处理逻辑

Nginx 默认不拦截后端返回的错误响应，必须显式开启拦截才能触发 error_page 指令：

在 location 或 server 块中设置 proxy_intercept_errors on;
用 error_page 499 = /error_handler; error_page 422 = /error_handler; 将指定状态码映射到内部 location
确保该 location 使用 internal; 防止外部直接访问

用内部 location 统一响应格式

定义一个内部处理器，可返回 JSON、重定向或静态页面：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

location = /error_handler {
    internal;
    # 可选：隐藏后端原始头（如 X-Powered-By）
    proxy_hide_header X-Powered-By;
    # 添加标准响应头
    add_header Content-Type "application/json; charset=utf-8";
    # 返回统一 JSON 错误结构
    return 200 '{"code":$status,"message":"请求处理失败","data":{}}';
}

注意：$status 是 Nginx 内置变量，值为被拦截的原始错误码（如 422）。

保留原始错误码或重写为标准码

若希望前端看到的是统一错误码（如全部转为 500），在 return 语句中指定目标状态码：

return 500 '{"code":500,"message":"服务异常"}'; → 客户端收到 500
若需保留原始码但只改响应体，用 return $status '...';
避免对 3xx 或 200 误配 error_page，它们不会被 proxy_intercept_errors 拦截

配合日志与调试技巧

验证是否生效可借助日志和响应头：

开启 error_log /path/error.log notice; 查看拦截日志（如 “upstream sent invalid response”）
用 curl -I http://your-domain/api 检查响应状态码和 Content-Type
若后端返回非标准状态码（如 499），确认 Nginx 版本 ≥ 1.11.13（早期版本对非 RFC 状态码支持有限）