Nginx代理WebSocket需透传Upgrade和Connection头、延长超时、禁用缓冲压缩缓存、精确路径匹配及正确HTTPS配置。核心是让Nginx识别并维持长连接，避免默认短连接行为导致频繁断开。
WebSocket 在 Nginx 代理下频繁断开，绝大多数情况不是后端或前端代码问题，而是 Nginx 把长连接当成了普通 HTTP 短连接来处理——它默认不维持空闲连接、不透传升级头、60 秒就主动切断。解决的核心是让 Nginx 明白：这不是一次请求，而是一条持续双向通道。
必须透传的两个协议升级头
WebSocket 握手依赖 Upgrade 和 Connection 两个逐跳请求头，Nginx 默认不转发，必须在匹配 WebSocket 路径的 location 块中显式配置：
-
proxy_set_header Upgrade $http_upgrade; —— 将客户端原始 Upgrade 头原样透传，不能写死为
"websocket"，否则无法兼容 MQTT、STOMP 等其他升级类型 -
proxy_set_header Connection "upgrade"; —— 注意双引号和字面量
"upgrade"，这是通知后端执行协议切换的关键指令；若写成$http_connection或漏掉引号，后端收不到信号，可能返回 400、200 或静默断连
超时时间必须大幅延长
WebSocket 是空闲时仍保持活跃的长连接，Nginx 默认 proxy_read_timeout 60 是高频断连的主因。三项超时需同步调整，且值应 ≥ 后端心跳间隔（例如后端每 30 秒发一次 ping，则 timeout 至少设为 60 秒）：
- proxy_read_timeout 86400; —— 控制 Nginx 等待后端推送数据的最大时间，适用于心跳较长场景
- proxy_send_timeout 86400; —— 防止大消息分片发送中途被中断
- keepalive_timeout 86400; —— 维持客户端与 Nginx 之间的 keep-alive 连接时长
禁用缓冲、压缩与缓存干扰
WebSocket 是流式通信，Nginx 的默认优化行为会破坏帧结构或延迟心跳，导致中间设备（如防火墙、云负载均衡）静默断连：
- proxy_buffering off; —— 禁用响应缓冲，否则可能缓存后端推送帧，造成粘包或 pong 延迟
-
gzip off; 或确保
gzip_types不含application/json、text/plain等常用类型 —— 压缩会改变帧边界，引发解析错误 -
proxy_cache off; 且不启用任何
proxy_cache_*指令 —— WebSocket 消息不可缓存，启用即导致连接失败
路径匹配与 HTTPS 配置要严丝合缝
配置错位会导致握手在 TLS 层或路由层就失败：
- 使用精确或前缀匹配的
location /ws/ { }，避免rewrite改写路径或 header；proxy_pass后不带斜杠（如http://backend;），确保路径原样透传 - 若走 WSS，
server块中必须有完整 HTTPS 配置：ssl_certificate、ssl_certificate_key、ssl_protocols TLSv1.2 TLSv1.3 - HTTP/2 不支持 WebSocket 升级，即使启用
http_v2，也必须保留proxy_http_version 1.1;
