Nginx代理WebSocket需同时配置三项：proxy_http_version 1.1；proxy_set_header Upgrade $http_upgrade；proxy_set_header Connection "upgrade"，缺一不可。
要让 Nginx 正确代理 WebSocket 或其他需要协议升级（如 HTTP/2 早期协商、某些 gRPC-Web 场景）的现代通信，proxy_set_header Upgrade $http_upgrade 是关键一环，但它必须配合其他配置才能生效。
为什么 Upgrade 头必须显式透传
客户端发起 WebSocket 连接时，会发送类似这样的请求头：
Upgrade: websocketConnection: upgrade
Nginx 默认不转发 Upgrade 头，也不会主动识别升级意图。$http_upgrade 是 Nginx 内置变量，它自动捕获客户端原始请求中的 Upgrade 值（比如 websocket），再通过 proxy_set_header Upgrade $http_upgrade 把它原样交给后端服务——这是握手成功的基础。
必须同步配置的三项核心指令
单独写 Upgrade 不起作用，以下三者缺一不可：
-
proxy_http_version 1.1;—— WebSocket 协议升级强制要求 HTTP/1.1，HTTP/1.0 会直接失败 -
proxy_set_header Upgrade $http_upgrade;—— 大小写敏感，$http_upgrade 不能写成 $HTTP_UPGRADE -
proxy_set_header Connection "upgrade";—— 引号不能省，值必须是小写upgrade，不是Upgrade或keep-alive
避免连接被意外中断
WebSocket 是长连接，Nginx 默认超时（60 秒）会主动断开空闲连接，导致频繁重连或 101 响应失败。建议补充：
-
proxy_read_timeout 86400;—— 设置为 24 小时，覆盖典型业务周期 -
proxy_send_timeout 86400;—— 防止后端响应延迟触发断连
若后端服务本身有心跳机制，也可设为 0（不限制），但需确保后端能稳定维持连接。
路径前缀与 Host 头处理
如果反向代理带路径前缀（例如 /ws/），location 必须严格匹配：
- 写成
location /ws/ { ... }，而非location / { ... } -
proxy_pass http://127.0.0.1:3000/;末尾斜杠不能多加（否则路径会被重复拼接） - 加上
proxy_set_header Host $host;或更严谨的$http_host，保留原始域名和端口信息 - 若前端走 HTTPS，后端需识别协议，建议加
proxy_set_header X-Forwarded-Proto $scheme;
