必须小写且带引号，即proxy_set_header connection "upgrade";，否则因大小写错误、缺引号或未配map块导致握手失败（400/426）；同时需配合proxy_http_version 1.1和proxy_set_header upgrade $http_upgrade。
proxy_set_header Connection "upgrade" 必须小写且带引号
很多配置抄来就用，结果 WebSocket 握手直接 400 或 426。关键就在 Connection 头的值：必须是小写的 "upgrade"，不能写成 "Upgrade"、upgrade（不带引号）、或 $connection_upgrade 却没配 map 块。Nginx 对这个值大小写敏感，且协议规范明确要求小写。漏掉引号会导致 Nginx 把它当变量解析，而该变量不存在，最终头被丢弃。
-
proxy_set_header Connection "upgrade";✅ 正确 -
proxy_set_header Connection upgrade;❌ 缺引号，Nginx 尝试展开变量upgrade，失败后不设头 -
proxy_set_header Connection "Upgrade";❌ 大写，部分严格客户端（如 iOS WKWebView）拒绝握手
proxy_http_version 1.1 是强制前提，不是可选项
HTTP/1.0 不支持 Upgrade 机制，而 WebSocket 握手本质就是一次 HTTP/1.1 的协议升级请求。如果只加了 Upgrade 和 Connection 头，却没设 proxy_http_version 1.1;，Nginx 仍会用 HTTP/1.0 转发请求——后端收不到合法升级信号，大概率返回 400 或静默断连。这个指令必须出现在 location 块内，且优先级高于全局设置。
- 缺这行，
Upgrade和Connection头即使存在也无效 - 不要放在
http或server块顶层，必须在具体location下 - 若用宝塔面板，在「反向代理」编辑页里，需手动补全这一行，图形界面默认不加
proxy_read_timeout 过短导致连接被主动关闭
WebSocket 建立后是长连接，但 Nginx 默认 proxy_read_timeout 是 60 秒。一旦连接空闲超时，Nginx 会直接断开 TCP，前端看到的就是“连接已关闭”或反复重连。这不是握手失败，而是运行期中断。Swoole 本身不依赖心跳，但 Nginx 会替你“代管”连接生命周期。
- 务必设为足够大，例如
proxy_read_timeout 3600s;（1小时） -
proxy_send_timeout同理，建议同步调大 - 别用
0或空值，Nginx 不识别；必须带单位，如s - 宝塔用户注意：其反向代理模板里可能只写了数字没单位，要手动补
s
前端 URL 写的是 localhost，但实际访问的是域名
这个坑最隐蔽：你在浏览器地址栏打开的是 https://yourdomain.com，但前端 JS 里写的却是 new WebSocket("ws://localhost:9502")。浏览器会把 localhost 解析成用户本机，而不是服务器，TCP 根本连不上，Nginx 日志里压根不会出现这条请求——所以查日志为空、curl 测试全通过，问题却死活不解决。
- 前端 WebSocket 地址必须与页面来源协议/域名一致：
wss://yourdomain.com或相对路径new WebSocket("/ws") - 绝对 URL 中的
localhost、127.0.0.1、内网 IP 在生产环境一律不可用 - Docker 环境下尤其要注意容器网络隔离，
host.docker.internal也不一定通
$http_upgrade 变量是否被正确捕获——它依赖客户端真实发送了 Upgrade: websocket 头，而某些测试工具（如老版本 wscat）或前端 SDK 可能默认不带，导致变量为空，Upgrade 头转发失败。动手前先用 curl -v -H "Upgrade: websocket" -H "Connection: upgrade" http://yourdomain.com/ws 实测响应头，比盲调配置高效得多。
