真正能用的 websocket 封装必须解决连接时机、url 编码、心跳保活、消息缓存、单例管理五点：onready 后连接、wss+encodeuricomponent、onsocketopen 后发首条消息、15–30s 心跳+指数退避重连、全局单例+消息缓存。
直接上结论：不封装 uni.connectSocket 就上线，等于把实时通信交给玄学——iOS 断连无声无息，小程序后台 30 秒失联，H5 切页就断，重连失败还不报错。真正能用的封装，必须解决连接时机、URL 编码、心跳保活、消息缓存、单例管理这五个硬点。
onReady 后才调 uni.connectSocket，别在 onLoad 或 mounted 里初始化
App 和小程序底层容器在 onLoad 阶段未必完成网络栈初始化，此时调 uni.connectSocket 常静默失败，success 回调不触发，fail 也不一定进——尤其 iOS 真机。Vue 的 mounted 在 App 端不等价于页面可交互，更不可靠。
- 正确做法：在页面
onReady生命周期里调用连接逻辑，这是跨端最稳定的“就绪信号” - 如果用了分包或 Vue Router，需加防重机制：检查全局
uni.$socket?.isConnected，为 true 就跳过本次 connect - H5 虽宽松，但为统一行为，所有平台强制走
onReady+ 网络状态校验（uni.getNetworkType）
url 必须是 wss://，且 query 参数必须 encodeURIComponent
微信/支付宝/抖音小程序强制要求加密协议，ws:// 直接报错；H5 和 App 端虽能连 ws://，但 CDN、Nginx 或网关通常只放行 wss://，生产环境一律用 wss://。
- Token、user_id 等敏感参数必须走 URL query，不能塞
header——小程序不支持自定义 header（content-type 除外） - 未编码的
+、空格、/会导致握手失败，错误信息典型为：fail err: {"errno":100001,"errMsg":"connectSocket:fail"} - 示例正确写法：
wss://api.example.com?token=abc%2Bdef&uid=12345（注意%2B是+的编码）
发消息前必须等 uni.onSocketOpen，data 只能是字符串或 ArrayBuffer
uni.connectSocket 的 success 回调只表示 TCP 握手完成，不代表 WebSocket 协议层已 ready。立刻调 uni.sendSocketMessage({ data })，90% 概率报 fail websocket not connected。
- 首条消息（如鉴权包）必须放在
uni.onSocketOpen的回调里发送 -
data字段只接受string或ArrayBuffer，传Object会静默丢弃，务必JSON.stringify() - 收消息时
event.data类型不确定：H5 可能是string或ArrayBuffer，小程序和 App 统一按服务端实际类型返回，必须先typeof event.data === 'string'判断再解析
心跳、重连、单例缺一不可，否则连接存活不过 2 小时
实测未封装的原生连接平均存活时间约 1.7 小时；加入心跳 + 指数退避重连 + 全局单例后，稳定性达 98%+。关键不是“有没有”，而是“怎么控”：
- 心跳间隔建议 15–30s，超时阈值设为间隔的 1.5 倍（如 30s 心跳，则 45s 未收到 pong 就判定断连）
- 重连必须指数退避：
3s → 6s → 12s，最大重试 3–5 次；错误码如10007（认证失败）、10008（token 过期）应直接终止重连 - 单例必须落地：把
socketTask存到uni.$socket或globalData，所有页面通过同一实例发消息，避免多连接导致消息乱序、资源泄漏 - App 进入后台时监听
uni.onHide主动uni.closeSocket()，切回前台再重连——系统会在后台 10–30 秒内强制回收连接，硬扛只会耗电、被杀进程
最容易被忽略的是消息缓存：连接未建立时用户发的消息，不能丢，得暂存在队列里，等 onSocketOpen 后批量重发；还有二进制粘包问题——服务端一次发多条，App 端可能合并成一个 ArrayBuffer，得自己加帧头或长度字段做分包。
