保障 WebSocket 握手需 Nginx 透传 Upgrade 和 Connection 逐跳头、设 proxy_http_version 1.1、动态转发 $http_upgrade、固定写 "upgrade"、关闭缓冲与缓存、路径隔离并校验升级请求，最终验证响应为 101 状态码及对应头。
保障 WebSocket 握手协议正确性，核心不是让 Nginx “理解” WebSocket，而是让它**不干扰、不过滤、不缓冲**一次标准的 HTTP/1.1 升级流程。漏掉任一关键配置，浏览器就会报 WebSocket handshake error 或返回 200 而非 101。
必须透传两个逐跳头（Hop-by-Hop Headers）
Upgrade 和 Connection 是 HTTP 协议中明确规定的逐跳头，Nginx 默认会删除它们。后端收不到这两个头，就无法触发协议升级，只能按普通 HTTP 处理：
- proxy_http_version 1.1：强制使用 HTTP/1.1。HTTP/1.0 不支持 Upgrade 机制，设为 1.0 或不写都会导致握手直接失败
-
proxy_set_header Upgrade $http_upgrade：用变量动态转发客户端原始值（如
websocket、mqtt），不能写死为"websocket"，否则非标准客户端或自定义协议会被截断 -
proxy_set_header Connection "upgrade"：必须是带英文双引号的字面量
"upgrade"，小写、不可省略引号；若写成$connection_upgrade但未提前定义 map，Nginx 可能发Connection: close，直接中断连接
关闭缓冲与缓存，确保 101 响应毫秒透传
WebSocket 握手依赖服务端快速返回 HTTP/1.1 101 Switching Protocols。任何中间缓冲或重写都可能延迟、截断甚至篡改响应头：
- proxy_buffering off：禁用响应体缓冲，避免 Nginx 积压数据、造成握手延迟或帧粘包
- proxy_cache off：防止 Nginx 将 Upgrade 请求误判为可缓存资源，返回 200 页面而非 101 响应
- 禁用
gzip on或其他响应重写模块：WebSocket 帧是二进制流，压缩可能破坏帧结构，且无实际收益
路径隔离 + 前置校验，减少无效流量干扰
把 WebSocket 流量与其他 HTTP 请求分开处理，既能避免规则冲突，又能提前拦截非法请求：
- 用明确路径匹配，例如
location /ws { ... }或location /socket.io { ... }，不要用location / { ... }兜底代理 - 加条件判断拒绝非升级请求：
if ($http_upgrade != "websocket") { return 403; }，降低后端负载 - 确保
proxy_pass地址末尾无斜杠（如http://backend:3000/ws），避免路径重写导致后端 404
验证是否真正生效
光写配置没用，得确认链路每一步都走通：
- 浏览器 Network 面板中，WebSocket 请求状态码必须是 101 Switching Protocols，Response Headers 中需含
Upgrade: websocket和Connection: upgrade - 用 curl 模拟握手：
curl -i -H "Connection: upgrade" -H "Upgrade: websocket" http://your-domain/ws，观察响应是否合规 - 检查 Nginx error log，常见错误如
upstream prematurely closed connection，通常指向后端未响应升级，或客户端发送了无效 Upgrade 头
