必须在 onready 后调用 uni.connectsocket，统一使用 wss:// 协议并 encodeuricomponent 编码 url 参数，token 只能放 query 中；发消息前监听 onsocketopen，data 必须是 string 或 arraybuffer；需手动实现心跳与指数退避重连。

直接用 uni.connectsocket 能连上，但不封装就等于裸奔——断连不重试、心跳没逻辑、多页面抢连接、token传错位置、切后台就失联，上线三天必出问题。

必须在 onReady 后调用 uni.connectSocket

App 和小程序对页面生命周期敏感，onLoad 阶段 WebView 或原生容器可能还没准备好，此时调用 uni.connectSocket 容易静默失败或触发异常回调。必须等 onReady 触发后再初始化连接，这是跨端最稳妥的时机。

• 别依赖 mounted（Vue2）或 onMounted（Vue3），它们在 App 端不等价于页面真正可交互
• 如果项目用了 Vue Router 或分包懒加载，还要确保路由守卫不会重复触发 connect()
• H5 端看似宽松，但为了一致性，所有平台统一走 onReady 后连接

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 参数

发消息前必须等 uni.onSocketOpen，且 data 只能是字符串或 ArrayBuffer

uni.connectSocket 回调成功 ≠ 底层通道已就绪。立刻调 uni.sendSocketMessage({ data }) 大概率报 fail websocket not connected。

WebSocket 8.18.2

WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。

下载

• 务必监听 uni.onSocketOpen，在它的回调里才开始发首条消息（比如鉴权包）
• data 字段只接受 string 或 ArrayBuffer，传 Object 会静默失败，必须手动 JSON.stringify()
• 服务端返回二进制数据时，H5 可设 binaryType: 'arraybuffer'，但 App 和小程序不识别该配置，一律按服务端实际类型接收
• 收消息统一用 uni.onSocketMessage，注意 event.data 类型不可预测，需先 typeof event.data === 'string' 判断再解析

必须手动实现心跳 + 指数退避重连

uni-app 不提供自动重连。掉线后不干预，用户就卡在“离线”状态。微信小程序甚至会在切后台时静默断连，根本不会触发 onSocketClose。

• 所有平台都必须主动发心跳包，不能等断连再处理
• 用 setTimeout 而非 setInterval 做心跳，避免多个定时器叠加（重连时旧定时器未清除）
• 心跳间隔设为 30s，服务端 ping_timeout 建议设为 45s，留出网络抖动余量
• 重连次数限制为 5 次，第 6 次起指数退避（如 1s → 2s → 4s → 8s），避免打爆服务端
• 每次重连前检查 uni.getNetworkType，无网络时不尝试，防止无效重试

最易被忽略的是：心跳响应必须由服务端回 pong 并本地记录时间戳，不能只靠定时器轮询；否则网络延迟波动时，会误判为断连。