必须在 onReady 后调用 uni.connectSocket，URL 用 wss:// 并 encodeURIComponent 编码参数，发送消息前监听 uni.onSocketOpen，断线重连需指数退避并过滤错误码，全局单例+心跳+缓存为必需。
直接用 uni.connectSocket 就能连，但不封装就等于裸奔——断连不重试、心跳没逻辑、多页面抢连接、Token传错位置、切后台就失联，上线三天必出问题。
为什么不能在 onLoad 里调 uni.connectSocket
App 和小程序对页面生命周期敏感，onLoad 阶段 WebView 或原生容器可能还没准备好，此时调用 uni.connectSocket 容易静默失败或触发异常回调。
- 必须等
onReady触发后再初始化连接，这是跨端最稳妥的时机 - 如果项目用了 Vue Router 或分包懒加载，还要确保路由守卫不会重复触发
connect() - H5 端看似宽松，但为了一致性，所有平台统一走
onReady后连接 - 别依赖
mounted（Vue2）或onMounted（Vue3），它们在 App 端不等价于页面真正可交互
uni.connectSocket 的 URL 必须是 wss://，且参数要 encodeURIComponent
小程序强制要求加密协议，ws:// 在微信/支付宝/抖音小程序里直接报错；H5 虽支持 ws://，但上线后 CDN、Nginx 或网关通常只放行 wss://，所以一律用 wss://。
- URL 中带 Token 或用户 ID 时，必须用
encodeURIComponent编码，例如：wss://api.example.com?token=abc+def→wss://api.example.com?token=abc%2Bdef - 未编码的
+、空格、/等字符会导致握手失败，错误信息通常是fail err: {"errno":100001,"errMsg":"connectSocket:fail"} - 不要把 Token 放在
header里传给小程序——微信和支付宝都不支持自定义 header（content-type除外），只能走 query 参数 - App 端虽支持 header，但为跨端一致，建议全部走 query +
encodeURIComponent
消息发送前必须等 uni.onSocketOpen，且 data 只能是字符串或 ArrayBuffer
uni.connectSocket 回调成功 ≠ 底层通道已就绪。立刻调 uni.sendSocketMessage({ data }) 大概率报 fail websocket not connected。
- 务必监听
uni.onSocketOpen，在它的回调里才开始发首条消息（比如鉴权包） -
data字段只接受string或ArrayBuffer，传Object会静默失败，必须手动JSON.stringify() - 服务端返回二进制数据时，H5 可设
binaryType: 'arraybuffer'，但 App 和小程序不识别该配置，一律按服务端实际类型接收 - 收消息统一用
uni.onSocketMessage，注意event.data类型不可预测，需先typeof event.data === 'string'判断再解析
断线重连不能靠 setTimeout 硬等，得用指数退避 + 错误码过滤
网络抖动、切后台、小程序被回收都会触发 uni.onSocketClose 或 uni.onSocketError，但不是所有断开都要重连。
- 监听
uni.onSocketClose：event.code === 1001是小程序主动断开（切后台），应清状态但不立即重连；event.code === 1006是异常关闭，才启动重连 - 监听
uni.onSocketError：部分错误如认证失败（401）、地址无效，重连毫无意义，需检查event.errMsg关键字后跳过 - 重连间隔必须指数增长：1s → 3s → 9s → 27s，避免密集请求打崩服务端或触发风控
- 最大重连次数建议设为 5，超过后进入“半休眠”状态，等用户操作（如点击刷新按钮）再试一次
全局单实例、心跳保活、消息缓存这些不是锦上添花，而是连接存活的底线——缺一不可。最容易被忽略的是：切后台时不主动 uni.closeSocket()，残留连接会在后台持续耗电并干扰下一次重连逻辑。
