Nginx配置WebSocket反向代理需三要素：透传Upgrade/Connection头、启用HTTP/1.1、延长超时；必须设proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade"，并定义map $http_upgrade $connection_upgrade规则，辅以proxy_read_timeout等稳定性配置。
直接配置 WebSocket 反向代理，核心就三件事：透传协议升级头、启用 HTTP/1.1、延长连接超时。Nginx 本身不处理 WebSocket 逻辑，只做“隧道中转”，配置错一行，前端就会卡在 WebSocket opening handshake 或几秒后断连。
必须设置的三个关键指令
WebSocket 握手依赖 Upgrade: websocket 和 Connection: Upgrade 这两个逐跳（hop-by-hop）请求头，而 Nginx 默认会过滤它们。需在 location 块中显式声明：
- proxy_http_version 1.1; —— HTTP/1.0 不支持协议升级，缺了这句握手必失败
-
proxy_set_header Upgrade $http_upgrade; —— 动态透传客户端原始 Upgrade 值（如
websocket、mqtt），不能硬写死 -
proxy_set_header Connection "upgrade"; —— 必须是固定字符串
"upgrade"，不是$http_connection（后者常含keep-alive，会覆盖升级意图）
需要提前定义的 map 规则
上面用到的 $http_upgrade 是客户端自带变量，但 $connection_upgrade 需要你手动定义（Nginx 1.3.10+ 支持）。把它加在 http 块顶层，不是 server 或 location 里：
default upgrade;
'' close;
}
这个规则的作用是：当客户端没带 Upgrade 头时，把 Connection 设为 close；带了就设为 upgrade，避免干扰普通 HTTP 请求。
推荐补充的稳定性配置
仅靠握手透传还不够，长连接容易被默认策略中断。建议在同一个 location 中追加：
- proxy_read_timeout 86400; —— 读取超时设为 24 小时，防止空闲时 Nginx 主动断连（默认仅 60 秒）
- proxy_send_timeout 86400; —— 发送超时同步调大，保障后端心跳或大数据帧不被截断
- proxy_buffering off; —— 关闭缓冲，避免多个 WebSocket 帧被合并发送，造成粘包或延迟
- tcp_nodelay on; —— 绕过 Nagle 算法，小数据（如实时光标、按键）立即发出
完整可运行示例（WSS 支持）
假设后端 WebSocket 服务跑在 localhost:8080，路径为 /ws，且需走 HTTPS（即 WSS）：
server localhost:8080;
}
server {
listen 443 ssl http2;
server_name example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location /ws {
proxy_pass http://ws_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header 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;
proxy_buffering off;
tcp_nodelay on;
}
}
