Nginx 中 proxy_pass 代理后的状态码处理逻辑-Nginx-PHP中文网

nginx的proxy_pass默认透传后端状态码，但可通过proxy_intercept_errors、proxy_redirect等指令干预；502/503/504由nginx自动生成，499为nginx特有状态码。

nginx 中 proxy_pass 代理后的状态码处理逻辑

Nginx 的 proxy_pass 本身不修改后端返回的状态码，它默认将上游响应原样透传给客户端。但实际状态码是否被更改、如何被处理，取决于配置中是否启用相关指令以及后端行为本身。

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

下载

Nginx 作为反向代理，收到后端响应后，若未显式干预，会直接把状态码（如 200、404、502、503 等）连同响应头和正文一并返回给客户端。
这意味着：

proxy_intercept_errors on + error_page
开启后，Nginx 会拦截后端返回的 4xx/5xx 响应（需配合 error_page 指令），转而返回自定义页面或重定向：
```
proxy_intercept_errors on;
error_page 502 /502.html;
location = /502.html {
    internal;
    root /usr/share/nginx/html;
}
```
proxy_redirect 控制跳转地址重写
当后端返回 301/302 且 Location 是内网地址（如 http://127.0.0.1:8080/path），可通过 proxy_redirect 重写为公网可访问地址：
```
proxy_redirect http://127.0.0.1:8080/ https://example.com/;
# 或使用 default 自动替换 Host 和端口
proxy_redirect default;
```
add_header 不影响状态码，但可补充响应头
比如统一添加 CORS 头或安全头，与状态码无关，但常与 error_page 配合使用：
```
add_header X-Proxy "nginx";
```
fastcgi_intercept_errors（仅限 FastCGI）
类似 proxy_intercept_errors，但专用于 PHP-FPM 等 FastCGI 场景，需搭配 fastcgi_pass 使用。

502 Bad Gateway：后端服务无响应（进程崩溃、端口未监听、超时）、或返回了非法 HTTP 响应（如空响应、格式错误）。
503 Service Unavailable：upstream 中 server 标记为 down，或健康检查失败且无可用节点。
504 Gateway Timeout：后端响应时间超过 proxy_read_timeout 或 proxy_connect_timeout 设置值。
400/404/499 等：多数来自后端应用本身；其中 499 是 Nginx 特有，表示客户端在 Nginx 发送响应前主动断开连接。

proxy_hide_header 可隐藏后端返回的特定响应头（如 Server、X-Powered-By），但不影响状态码。
proxy_set_header 只影响发往后端的请求头，对响应状态码无作用。
状态码逻辑发生在 proxy_pass 执行后的响应阶段，与 rewrite 或 return 等指令互不干扰——除非 return 在 location 中提前终止流程。

不复杂但容易忽略。