真机 wx.connectsocket 失败主因是微信三层校验：域名未入白名单（仅填 api.example.com，禁带协议/端口）、必须用 wss:// 协议、tls 1.2+ 且证书由可信 ca 签发并链完整；nginx 需透传 upgrade/connection 头，后端须复用 https 实例。
真机上 wx.connectSocket 或 uni.connectSocket 一直失败，90% 不是代码写错了，而是卡在微信的三层校验链上：域名没进白名单、协议不是 wss://、证书或 TLS 版本不达标。开发工具能连 ≠ 真机能连，这是环境差异，不是 bug。
微信后台“socket 合法域名”填错是最常见原因
错误现象：域名协议头非法、connectSocket:fail invalid domain；实际就是你往「开发管理 → 服务器域名 → socket 合法域名」里填了带协议或路径的内容。
- ✅ 正确写法：
api.example.com（纯二级/三级域名，不带任何前缀后缀） - ❌ 错误写法：
wss://api.example.com、api.example.com:443、api.example.com/socket - 备案主体必须和小程序账号主体一致（个人备案通常不被接受，需企业主体）
- 如果用的是
ws.example.com这类二级域名，它本身也得单独完成 ICP 备案，不能只备example.com - 填完不用等审核通过，配置实时生效；但每月仅 5 次修改机会，务必核对后再提交
wss:// 是硬性要求，ws:// 在真机下直接被拦截
开发工具允许 ws:// 是为了调试便利，真机环境会直接拒绝该协议请求，错误可能表现为静默失败、Invalid HTTP status 或 ERR_CONN。
- 客户端 URL 必须写成
wss://api.example.com/socket（注意是wss，不是ws） - 后端若跑在非 443 端口（如
:9603），需用 Nginx 反向代理到标准 HTTPS 端口，否则部分安卓机型或运营商可能拦截 - 不要在代码里拼接协议头，比如
url: protocol + '://' + host + '/socket'——protocol值为ws时，真机就废了
TLS 与证书问题导致 handshake failed
看到 {"errCode": 1004, "errMsg": "open fail: _code:8,_msg:TLS handshake failed"}，说明连接卡在 TLS 握手阶段，和业务逻辑完全无关。
- 证书必须由可信 CA 签发（Let’s Encrypt、DigiCert、Sectigo 等），自签名证书真机一律拒绝
- 必须支持 TLS 1.2+，Nginx 配置中要显式开启：
ssl_protocols TLSv1.2 TLSv1.3; - 证书链要完整：中间证书不能缺失，可用
openssl s_client -connect api.example.com:443 -servername api.example.com检查 - 后端 WebSocket 服务（如 Node.js 的
ws库）必须复用 HTTPS server 实例，不能另起 HTTP server 再升级 —— 否则 Upgrade 头会被丢弃
后端未透传关键 HTTP 头也会静默失败
微信在发起 WebSocket 握手时，会带上 Upgrade: websocket 和 Connection: Upgrade，还可能带 Origin。如果反代层（如 Nginx）或网关过滤/重写了这些头，握手直接失败，且不报具体错误。
- Nginx 配置中必须显式透传：
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";
https://servicewechat.com）或干脆跳过校验（小程序 Origin 不稳定，不建议强校验）最容易被忽略的是：你以为配好了域名、用了 wss、证书也没问题，但 Nginx 没透传 Upgrade 头，或者后端用了不兼容的 WebSocket 库（比如没适配 TLS 的裸 ws server），这种失败不会抛出明确错误，只会卡在连接建立前 —— 建议用真机抓包（Chrome Remote Debugging）看第一个 HTTP 请求是否返回 101 Switching Protocols。
