proxy_pass 是 Nginx 实现反向代理最核心的指令，决定请求转发目标；其路径结尾是否带斜杠直接影响 URI 重写行为，需配合 proxy_set_header 等指令传递真实客户端信息，并针对重定向、WebSocket、超时等场景做必要配置。

proxy_pass 是 Nginx 实现反向代理最核心的指令，它直接决定请求被转发到哪个后端地址。配置本身不难，但细节容易出错，尤其在路径重写、协议兼容和 header 传递方面。

基础 proxy_pass 配置写法

最简形式是在 location 块中指定后端服务地址：

• 后端是 HTTP 服务（如 Node.js、Python Flask）： proxy_pass http://127.0.0.1:3000;
• 后端是 HTTPS 服务（需确保 Nginx 编译时启用了 SSL 支持）： proxy_pass https://backend.example.com;
• 使用 upstream 定义多个节点实现负载均衡：

  upstream app_servers { server 10.0.1.10:8000; server 10.0.1.11:8000; }  
  location /api/ { proxy_pass http://app_servers; }

路径处理的关键细节

proxy_pass 后是否带 URI 路径，会显著影响请求路径的转发行为：

WebChat Voice Proxy

⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**

下载

• proxy_pass http://127.0.0.1:8000;（结尾无斜杠）→ Nginx 会把原始 location 匹配的路径完整拼接过去。例如访问 /api/v1/user，实际发给后端的是 /api/v1/user。
• proxy_pass http://127.0.0.1:8000/;（结尾有斜杠）→ Nginx 会**截掉 location 的匹配前缀**，再拼接。例如：location /api/ { proxy_pass http://127.0.0.1:8000/; }，访问 /api/v1/user 会转发为 /v1/user。

这个区别常导致 404，务必根据后端路由规则选择是否加末尾斜杠。

必须配套设置的常用代理头

默认情况下，Nginx 不会转发原始客户端的真实 IP 和协议信息，后端可能拿到的是 Nginx 本机地址或错误的 scheme。需手动补充：

• proxy_set_header Host $host; —— 保持原始 Host 头
• proxy_set_header X-Real-IP $remote_addr; —— 传真实客户端 IP
• proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; —— 支持多层代理链
• proxy_set_header X-Forwarded-Proto $scheme; —— 标明是 http 还是 https，便于后端做跳转判断
• proxy_set_header X-Forwarded-Host $host; —— 保留原始域名

常见问题与应对建议

实际部署中高频踩坑点：

• 后端返回 302 重定向时跳转地址错误 → 加上 proxy_redirect off; 或显式重写跳转地址，例如 proxy_redirect http://127.0.0.1:8000/ /;
• WebSocket 连接失败 → 需额外添加升级头：proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";
• 大文件上传超时 → 设置超时参数：proxy_connect_timeout 60; proxy_send_timeout 120; proxy_read_timeout 120;
• 后端响应体过大被截断 → 检查并调大 proxy_buffer_size 和 proxy_buffers