Nginx转发WebSocket需配置proxy_http_version 1.1及透传Upgrade、Connection头，使用$connection_upgrade变量动态设置，配合超时调优和路径/协议一致性即可稳定工作。
要让 Nginx 网关正确转发 WebSocket 请求，核心是配置好协议升级（Upgrade）和连接保持（Connection）头，并确保后端服务能识别被代理后的 WebSocket 连接。Nginx 本身不处理 WebSocket 逻辑，只做透传，但必须显式允许 HTTP 协议切换。
必须设置的 WebSocket 关键头字段
Nginx 默认会过滤掉 Upgrade 和 Connection 请求头，而 WebSocket 握手依赖这两个字段。需在 location 块中显式透传：
- proxy_http_version 1.1;：强制使用 HTTP/1.1（WebSocket 升级仅支持该版本）
- proxy_set_header Upgrade $http_upgrade;：将客户端的 Upgrade 头（通常是 "websocket"）原样传给后端
- proxy_set_header Connection $connection_upgrade;：动态控制 Connection 头——若原始请求含 Upgrade，则设为 "upgrade"；否则保持 "close"
完整可用的 Nginx 配置示例
假设后端 WebSocket 服务运行在 localhost:8080，路径为 /ws：
upstream ws_backend {
server localhost:8080;
}
<p>server {
listen 80;
server_name example.com;</p><pre class="brush:php;toolbar:false;">location /ws {
proxy_pass http://ws_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
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;
# 可选：延长超时，避免空闲断连
proxy_read_timeout 86400;
proxy_send_timeout 86400;
}}
注意：$connection_upgrade 是 Nginx 内置变量（需 1.3.10+），它会根据 $http_upgrade 是否非空自动设为 "upgrade" 或 "close"，不能硬写死。
常见失败原因与排查要点
WebSocket 连接 400 或直接断开，大概率是以下问题之一：
- 后端服务未监听 Nginx 转发后的请求路径（例如 Nginx 配置了
/ws，但后端只响应/） - SSL 终止在 Nginx 时，后端未适配
X-Forwarded-Proto: wss，误判协议为 http 导致拒绝握手 - 浏览器控制台显示
Error during WebSocket handshake: Unexpected response code: 200→ 后端返回了 HTML 或普通 HTTP 响应，未进入 WebSocket 升级流程 - 防火墙或云厂商 SLB 拦截了长连接，需确认中间链路支持 WebSocket（如阿里云 ALB 需开启“WebSocket 支持”开关）
HTTPS + WSS 场景下的额外注意
若前端用 wss://，Nginx 必须启用 SSL 并正确传递协议信息：
- 配置
ssl_certificate和ssl_certificate_key - 确保
proxy_set_header X-Forwarded-Proto $scheme;已设置，后端据此判断是否启用 TLS - 避免在 Nginx 和后端之间再套一层不支持 upgrade 的代理（如某些老旧负载均衡器）
只要头字段透传准确、超时合理、路径匹配，Nginx 作为 WebSocket 反向代理非常稳定可靠。不复杂但容易忽略细节。
