Nginx代理WebSocket需正确透传Upgrade和Connection头并禁用缓冲：设proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade"，关闭proxy_buffering，延长proxy_read_timeout和proxy_send_timeout。
Nginx 代理 WebSocket 时，核心在于正确透传 Upgrade 和 Connection 请求头，并关闭 HTTP/1.0 代理缓冲——否则握手会失败，连接降级为普通 HTTP。
必须设置的代理头字段
WebSocket 握手依赖特定 HTTP 头完成协议升级，Nginx 默认不转发这些头，需显式配置：
- proxy_http_version 1.1：强制使用 HTTP/1.1（Upgrade 机制仅在 1.1 中有效）
-
proxy_set_header Upgrade $http_upgrade：将客户端发来的
Upgrade: websocket原样透传 -
proxy_set_header Connection "upgrade"：固定写死为
"upgrade"（注意加引号），而非继承客户端的Connection值（可能含 keep-alive 等干扰项）
禁用缓冲与超时控制
WebSocket 是长连接，Nginx 默认的响应缓冲和短超时会中断握手或导致后续帧丢弃：
- proxy_buffering off：关闭响应缓冲，避免 Nginx 缓存未结束的响应体
- proxy_read_timeout 86400：大幅延长读超时（单位秒），防止空闲时连接被主动断开
- proxy_send_timeout 86400：同理，保障服务端推送不因发送延迟被切断
location 匹配与协议校验
建议用明确路径匹配（如 /ws/）而非泛匹配，便于隔离 WebSocket 流量：
- 确保
location块中不启用gzip或sub_filter等可能修改响应体的模块 - 后端服务返回的
101 Switching Protocols响应不能被 Nginx 拦截或重写（默认不会，但需确认无error_page或add_header干扰） - 若后端校验
Origin头，可通过proxy_set_header Origin $http_origin透传（按需）
常见失败原因速查
握手失败（返回 200 而非 101）通常源于以下配置缺失或错误：
- 漏掉
proxy_set_header Connection "upgrade"（最常见） -
$http_upgrade变量为空 → 客户端未发Upgrade: websocket，检查前端是否正确调用new WebSocket(url) - 后端监听地址写错（如写成
http://127.0.0.1:8080但实际服务监听localhost或 IPv6） - HTTPS 站点反向代理到 HTTP 后端时，未在后端适配
X-Forwarded-Proto: wss（部分框架依赖此判断安全上下文）
