真机上 websocket 必须用 wss:// 协议且域名备案，app 切后台会断连需指数退避重连，各端消息类型不一致须类型判断，应采用全局单例+消息队列管理。
直接用 uni.connectSocket 在真机上八成连不上——不是代码错，是协议、域名、生命周期没对齐。
为什么 wss:// 是硬性门槛，ws:// 在真机必然失败
iOS/Android 原生 WebView 和所有小程序平台（微信、支付宝）都强制要求加密连接。本地开发用 ws://localhost:8080 能跑通 H5，但一到真机或小程序，onOpen 就不触发，也不报错，连接被静默丢弃。
- 必须使用
wss://协议，且证书有效（自签名证书在 iOS 上大概率被拒） - 微信/支付宝小程序：域名必须在后台「开发管理 → socket 合法域名」中备案并上线
- App 端：
manifest.json的「SDK 配置 → WebSocket 合法域名」必须显式填写，否则连接无声失败 - URL 中带未编码参数（如
?token=abc+def）会导致 App 端解析中断；务必用encodeURIComponent处理所有 query 字段
onMessage 收到 ArrayBuffer 就崩？类型判断不能省
uni.onSocketMessage 的 res.data 类型在各端完全不一致：H5 可能是 string，App 和小程序更倾向返回 ArrayBuffer，尤其当服务端发的是二进制帧或高并发下粘包时。
WebSocket 8.18.2
下载
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
- 绝对不要写
JSON.parse(res.data)—— 一旦res.data是ArrayBuffer，直接抛SyntaxError - 必须先判断：
typeof res.data === 'string'才走 JSON 解析；否则用new TextDecoder().decode(res.data) - 服务端发多条消息时，App 端可能合并或拆分回调；前端需自行按协议做帧解析（如加长度头、分隔符），不能依赖单次回调 = 单条业务消息
- 发送前统一
JSON.stringify()，禁用uni.sendSocketMessage({ data: { a: 1 } })这种传对象写法 —— App 端会静默失败
App 切后台就断连，重连策略必须带退避和节流
iOS/Android 系统会在 App 进入后台 10–30 秒后强制回收 WebSocket 连接。这不是 bug，是系统行为。无脑轮询重连只会耗电、被杀进程、触发限频。
-
uni.onHide触发时，立刻执行uni.closeSocket()并清空状态（this.socketTask = null），避免残留连接干扰后续逻辑 -
uni.onShow里检查socketTask?.readyState === 1，仅当断开才调用重连，不无脑发起新连接 - 重连间隔必须指数退避：
3s → 6s → 12s，最多试 3 次；超过阈值应降级为轮询或提示用户手动重试 - 认证失败（如服务端返回 401）、协议错误等明确不可恢复的错误，要过滤掉，禁止重连
全局单例 + 消息队列才是多页面通信的底线
每个页面都 new 一个 WebSocket 实例，等于在手机里养了一群“僵尸连接”——流量涨、发热快、服务器压力翻倍，还容易消息重复或丢失。
- 必须实现单例模式：
class SocketClient { constructor() { if (SocketClient.instance) return SocketClient.instance; SocketClient.instance = this; } - 连接未就绪（
readyState !== 1）时，send()应把消息推入this.msgQueue = []，连接建立后再批量 flush - 用
Map或Set管理事件监听器（on('message', cb)），支持页面卸载时off('message', cb)，避免内存泄漏 - 心跳消息建议用纯文本（如
'ping'），避免 JSON 序列化开销；心跳间隔设 15–30 秒，太短加重负担，太长易被网关踢出
跨端 WebSocket 封装最难的不是写代码，而是接受“各端根本不是同一个东西”这个事实——iOS 的静默断连、小程序的域名白名单、App 的 manifest 配置，全是运行时确定的约束。任何想靠一套配置打遍天下的思路，都会在真机上撞墙。
