Nginx的proxy_pass是反向代理核心指令，关键在路径拼接逻辑与代理头设置：以路径结尾则截前缀再拼接，否则保留完整路径；必须配置Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto等头信息以透传客户端真实信息。
Nginx 通过 proxy_pass 指令可将客户端请求转发给后端服务（如 Node.js、Python Flask、Java Spring Boot 等），是反向代理最核心的配置项。正确使用它，关键在于理解 URL 路径的拼接逻辑和代理头的设置。
基础语法与路径处理规则
proxy_pass 后面跟的 URL 决定了请求如何被重写和转发：
- 若
proxy_pass值以 具体路径结尾（如http://127.0.0.1:3000/api/），Nginx 会截掉 location 匹配的前缀，再拼接到该路径后。例如：
location /api/ { proxy_pass http://127.0.0.1:3000/api/; }
访问/api/users→ 实际转发为http://127.0.0.1:3000/api/users - 若
proxy_pass值不带路径或仅以主机名结尾（如http://127.0.0.1:3000），则 location 匹配的路径会被完整保留并追加。例如：
location /api/ { proxy_pass http://127.0.0.1:3000; }
访问/api/users→ 实际转发为http://127.0.0.1:3000/api/users - 注意：当 location 使用正则匹配（如
~ ^/api/）时，proxy_pass不能省略 URI 部分，否则会报错；必须显式指定完整目标地址（含路径或空路径）。
必须设置的代理头信息
后端服务常依赖原始请求信息（如真实 IP、协议类型）做日志、鉴权或重定向。默认 Nginx 不传递这些，需手动添加：
-
proxy_set_header Host $host;—— 保持原始 Host 头，避免后端因 Host 错误返回 404 或跳转异常 -
proxy_set_header X-Real-IP $remote_addr;—— 传递客户端真实 IP（尤其在有 CDN 或多层代理时） -
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;—— 补充 IP 链路，支持多级代理识别 -
proxy_set_header X-Forwarded-Proto $scheme;—— 告知后端当前是 http 还是 https，便于生成正确跳转链接
常见问题与规避方式
以下配置错误高频出现，直接影响功能可用性：
-
尾部斜杠不一致导致 404：location 和 proxy_pass 路径结尾斜杠含义不同。建议统一风格——location 用
/api/，proxy_pass 也用http://backend/api/，避免歧义 -
后端重定向失败（302 跳转到内网地址）：因为后端生成 Location 响应头时用了自己的 host/port。解决方法是让后端读取
X-Forwarded-Proto和Host头，或在 Nginx 层用proxy_redirect重写响应头中的跳转地址 -
WebSocket 连接中断：需额外开启升级支持：
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
完整示例（带 HTTPS 适配）
假设前端域名 app.example.com，后端运行在 127.0.0.1:8080，且需透传 HTTPS 信息：
location /api/ {
proxy_pass http://127.0.0.1:8080/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
<pre class="brush:php;toolbar:false;"># 可选：超时调优
proxy_connect_timeout 30s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;}
这样配置后，所有以 /api/ 开头的请求都会精准转发，后端能获取真实用户信息和协议类型，不易出错。
