websocket握手失败的根本原因是服务端监听地址未设为0.0.0.0或公网ip，导致外部请求无法到达；需同步检查nginx upgrade头透传、wss证书配置合规性及防火墙端口放行，缺一不可。
Workerman WebSocket握手失败时，浏览器控制台常报“WebSocket connection to 'wss://' failed: error during websocket handshake”，连接卡在CONNECTING状态且无101响应，说明协议升级流程在某一层被截断或拒绝。
确认服务端监听地址是否对外可访问
Workerman默认绑定127.0.0.1，仅限本机访问，外部请求必然失败。【必须改成本机IP或0.0.0.0】
打开Worker启动文件（如start.php或workercontroller.php），检查$socket配置项：若为websocket://127.0.0.1:2222，需改为websocket://0.0.0.0:2222或websocket://你的服务器公网IP:2222。
修改后执行php start.php restart强制重启服务，避免旧进程残留。
用telnet 服务器IP 端口（如telnet 47.98.x.x 2222）验证端口是否真正开放——如果连接超时或拒绝，说明服务未生效或防火墙拦截。
检查Nginx反向代理是否透传Upgrade头
使用Nginx作前置代理时，缺一不可的三行配置必须出现在对应location块中：
方法一：基础配置校验
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
方法二：补全关键头（易漏）
务必加上proxy_set_header Host $host;，否则某些鉴权逻辑可能因Host为空拒绝握手；
若启用HTTPS终结，确保SSL证书链完整，否则wss握手会在TLS层中断，浏览器不发Upgrade请求。
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
执行nginx -t验证语法无误后，运行nginx -s reload重载配置。注意：reload不等于restart，旧worker进程可能缓存旧配置。
验证wss证书与端口暴露是否合规
微信小程序、iOS Safari等环境强制要求wss，且对证书极为敏感。
第一步：确认Workerman启动方式
必须使用ssl://协议，例如ssl://0.0.0.0:8443，不能用websocket://或tcp://再套Nginx SSL——双重加密会导致握手失败。
第二步：检查ssl_context参数
local_cert必须指向fullchain.pem（不是cert.pem），local_pk指向privkey.pem，路径用绝对路径，如__DIR__ . '/certs/fullchain.pem'；
【开发环境务必设'verify_peer' => false，否则localhost或IP域名校验必失败】
第三步：验证端口是否放行
云服务器安全组、本地iptables、宝塔防火墙三处都要放开wss端口（如8443），不能只开80/443；
用手机浏览器直访wss://your-domain.com:8443，若提示“无法建立安全连接”或空白页，说明证书或端口问题尚未解决。
抓包定位握手在哪一层中断
浏览器Network面板中筛选ws/wss请求，点击查看Headers → Response部分：
① 若无任何响应，TCP连接就断了 → 检查防火墙、DNS解析、服务器是否宕机；
② 若响应状态码是400/403/502 → 查Nginx error.log，常见于Upgrade头被过滤或后端服务未监听；
③ 若状态码是200但无101 → 后端未正确处理Upgrade请求，或PHP-FPM模式下无法维持长连接；
④ 若出现101但立即断开 → 检查Sec-WebSocket-Protocol子协议是否匹配，或服务端onConnect逻辑抛出异常。
服务端加日志：在onConnect回调开头插入file_put_contents('/tmp/ws.log', print_r($connection, true), FILE_APPEND)；若该日志完全无记录，说明握手根本未到达Workerman进程。
