uni.connectSocket 是唯一跨端 WebSocket 入口，必须用 wss:// 协议并 encodeURIComponent 参数；需在 onReady 后连接、onSocketOpen 后发消息；心跳与重连须手动实现；推荐全局单例管理连接状态。

uni.connectSocket 是唯一能打通微信小程序、App 和 H5 的入口，别碰 new WebSocket()——它在小程序和 App 里根本不会执行，H5 虽然能跑，但一编译就断，跨端直接失效。

连接必须用 wss:// 且参数要 encodeURIComponent

微信小程序强制要求 wss:// 协议，H5 和 App 也得统一，否则上线后连不上。URL 带查询参数（比如 ?token=abc+def）没问题，但必须用 encodeURIComponent 处理，否则 + 变空格，服务端解析失败，鉴权直接拒绝。

• url: `wss://your-api.com/ws?token=${encodeURIComponent(token)}`
• 别在 onLoad 里调 uni.connectSocket，页面还没挂载完，App 端大概率静默失败
• 等 onReady 触发后再连，更稳；可加一层 uni.getNetworkType 校验网络再发起

首条消息只能在 uni.onSocketOpen 里发

uni.connectSocket 的 success 回调只表示 TCP 握手完成，不代表 WebSocket 协议层已 ready。此时调 uni.sendSocketMessage，90% 概率报 fail websocket not connected。

• 收消息用 uni.onSocketMessage，注意 event.data 类型由服务端决定：文本是 string，二进制是 ArrayBuffer，不能硬假设是字符串
• 发 JSON 必须先 JSON.stringify()，data 只接受 string 或 ArrayBuffer，传对象会静默丢弃
• H5 支持 binaryType: 'arraybuffer' 配置，但小程序和 App 完全忽略，一律按服务端帧类型处理

心跳和重连必须手动实现，不能靠 onSocketClose

微信小程序切后台时不会触发 onSocketClose，而是静默断连；H5 页面休眠后也可能延迟甚至不触发。光监听 onSocketClose 会漏掉大量真实断连。

PigX UI 前端开发

PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。

下载

• 所有平台都必须主动发心跳包，建议间隔 30s，服务端 ping_timeout 设为 45s 左右
• 用 setTimeout 控制心跳，避免 setInterval 在重连时叠加多个定时器
• 重连前先查网络状态：uni.getNetworkType 返回 none 就别试，防止无效请求
• 重连次数限制为 5 次，之后启用指数退避（1s → 3s → 9s…），避免打爆服务端
• 小程序 onHide 里应主动 uni.closeSocket() 并清状态，resume 时不带残留连接

全局单例管理比页面级连接更可靠

每个页面都 new 一个 socket，不仅浪费资源，还会冲垮 Workerman 后端。Workerman 本身支持海量并发，但前提是连接是“有意图”的，不是被前端无序创建的垃圾实例拖垮的。

立即学习“前端免费学习笔记（深入）”；

• 把 socket 初始化、发送、重连逻辑抽到 socket.js 或 main.js，暴露 send()、onMessage() 等方法
• 各页面通过 import 或 uni.$emit/uni.$on 通信，避免重复连接
• 连接状态（connecting / open / closed）必须集中维护，页面只读不写
• Workerman 端记得在 onMessage 中更新 $connection->lastMessageTime，并配一个全局定时器清理超时连接

真正难的不是连上，而是连上之后没人管——没人清定时器、没人判 code 是 1001 还是 1006、没人把 onHide 和 onShow 对齐 socket 生命周期。这些细节堆在一起，才让长连接“看起来稳定”。