uniapp 微信小程序 WebSocket 封装实战：心跳保活与断线重连

前阵子处理一个商城客服小程序，用户在售后页发起会话，客服端经常收不到消息，查到最后居然是 WebSocket 连接被服务端悄悄踢了，而前端完全不知情，也没做重连。这种问题在微信小程序里太常见了——uniapp 做微信小程序开发出活确实快，但 WebSocket 这个环节，真的是文档写得越简单，坑埋得越深。

这篇文章不打算照搬官方文档复读 API，而是把我在 uniapp 项目里真正跑通过的 WebSocket 封装思路、连接状态管理、心跳保活、断线重连、消息路由这些实操内容摊开讲。同时会带一下 uniapp 做微信小程序的工程配置，方便刚上手的同学直接照着落地。适合正在用 uniapp 做微信小程序，并且业务里绕不开长连接、实时推送的开发者参考。

1. 先搞清楚：uniapp 做微信小程序到底图什么

1.1 多端复用是最大的账

很多刚入门的朋友会问：如果我只做微信小程序，为什么还要用 uniapp，直接写原生小程序不就行了？这个问题的答案不复杂。uniapp 的核心价值在于一套代码编译到微信小程序、支付宝小程序、抖音小程序、H5 和 App 等多个端，你要是业务已经覆盖了小程序和 H5，用 uniapp 能省下至少一半的开发量。

我自己接过一个内部管理工具项目，管理端要求 H5 能访问，员工又希望能在微信里打开小程序查看工单进度。如果用两套技术栈去写，光维护接口联调和 UI 一致性问题就够呛。换成 uniapp 之后，业务代码基本只写一遍，差异部分用条件编译处理，两个端口同步上线，性价比立竿见影。

如果你只做单一微信小程序，uniapp 也依然有它的价值。一个是它对 Vue 语法友好，团队如果有 Vue 基础，几乎零成本切换；还有一个是 uniapp 封装过的 API 和插件生态，社区里沉淀了大量现成方案，省去了不少从零开发的时间。当然，原生小程序能更精细地拿到底层能力，如果你要深度使用小程序内部的高阶硬件能力，还是得评估一下是否需要回到原生或者做混写。

1.2 工程配置清单与开发前置准备

用 uniapp 跑微信小程序，常规流程是：拿 HBuilderX 新建一个默认项目，把运行目标选成“微信开发者工具”。这里有个非常影响体验的小细节：微信开发者工具默认没有开放外部调用端口，你必须在工具右上角的“设置 -> 安全设置”里打开服务端口，不然 HBuilderX 的编译结果发送不过去。

项目跑起来之后，有两个文件是绕不开的：

• pages.json：负责配置页面路由、窗口样式、tabBar 等页面级信息。新建页面时首先要在这里注册，否则路径访问不到。
• manifest.json：负责配置应用级信息。你要在“微信小程序配置”一栏里填上小程序的 AppID，如果是测试项目可以填测试号，但预览真机和上传发布的时候必须填正式 AppID。

还有一个基本功建议早点掌握：条件编译。小程序端和 H5 端在能力上有差异，比如小程序里可以使用wx.login做静默登录，而 H5 端没有这个能力，这时候用条件编译分隔代码段比较干净：

// #ifdef MP-WEIXIN const code = await wxLogin() // #endif // #ifdef H5 const code = await getH5LoginCode() // #endif

MP-WEIXIN 表示微信小程序端，H5 表示网页端。这样一套代码里可以按平台走不同逻辑，又不影响其他端的编译。

2. WebSocket 在小程序里的正确打开方式

2.1 长连接和 HTTP 到底差在哪

先花一分钟把概念理清楚。HTTP 是典型的请求-响应模型，客户端不发请求，服务器就绝对不能主动推送数据。你要做实时功能，比如聊天消息、订单状态变更、扫码结果通知，最常见的老办法是轮询：前端每隔几秒发一次 HTTP 请求去问服务器“有没有新数据”。

轮询在低并发、低频率场景下勉强能用，但实时性永远是差的——你说 3 秒查一次，消息到达后最多要白白等 3 秒；你说 1 秒查一次，请求量直接翻几十倍，服务器压力感人，用户流量的电也烧得飞快。WebSocket 解决的就是这个问题：它一次握手建立 TCP 长连接，之后客户端和服务端随时可以双向发送数据，延迟以毫秒计。

微信小程序里 WebSocket 的典型业务场景包括在线客服、协同编辑、实时定位上报、交易行情推送、扫码登录结果回传等等。我这边踩坑最多的客服系统，消息体本身不大，但是量级高，用户一句一句发过来，用 HTTP 轮询简直是灾难，换成 WebSocket 之后反过来还要担心消息太快看不过来。

2.2 uniapp 的 WebSocket API 与关键细节

uniapp 封装了一套跨端的 WebSocket API，核心方法如下：

• uni.connectSocket：发起连接，返回 SocketTask 对象
• SocketTask.onOpen：连接成功回调
• SocketTask.onMessage：收到服务端消息回调
• SocketTask.onError：连接出错回调
• SocketTask.onClose：连接关闭回调
• SocketTask.send：发送消息
• SocketTask.close：主动关闭连接

注意看，我这里写的是 SocketTask 的方法，而不是uni.onSocketOpen、uni.onSocketMessage那套旧版全局监听 API。这两者最大的区别是：旧版全局监听是 app 级别的，所有页面都共享回调，一旦多个页面同时开了连接，消息就会串台；新版 SocketTask 是连接实例自带的方法，每个连接回调独立，管理起来清晰得多。新项目建议直接使用 SocketTask 方案。

一个基础连接示例大概是这样的：

const task = uni.connectSocket({ url: 'wss://your-domain.example.com/ws', complete: () => {} }) task.onOpen(() => { console.log('连接已打开') }) task.onMessage((res) => { console.log('收到消息', res.data) }) task.onError((err) => { console.log('连接异常', err) }) task.onClose(() => { console.log('连接已关闭') })

有一个最容易被忽略的点：微信小程序要求 WebSocket 的 URL 必须使用wss://前缀，也就是加密过的 WebSocket 协议，开发期间可以在开发者工具里勾选“不校验合法域名”来跳过检查，但真机预览和生产环境必须在微信公众平台后台配置 socket 合法域名，否则连接会直接失败，报的错还模棱两可。这一点每做一个新项目我都会踩一遍，先确认后台域名有没有配准，再去排查代码。

另外，SocketTask.send发送的内容只支持字符串和 ArrayBuffer。日常业务消息基本都转成 JSON 字符串再发：

task.send({ data: JSON.stringify({ type: 'chat', payload: { text: '你好' } }) })

3. 合理使用 WebSocket：一套能上生产的封装

3.1 全局单例连接管理

很多同学写 WebSocket 是“页面级”思维：聊天页面需要就连，页面销毁就关。这在小程序里是行不通的。用户从小程序的一个页面跳到另一个页面，连接如果跟着页面销毁，再跳回来又建一次，服务端连接反复创建销毁，既慢又浪费资源，更重要的是跨页面的消息推送没法做。

我的做法是维护一个模块级的单例类，把连接生命周期统一管理起来，所有页面共用同一条连接。类内部维护连接状态，外部只暴露 connect、send、onMessage 注册接口。这样无论用户切到哪个页面，连接始终在，消息也能按频道派发给对应页面。

class WebSocketManager { constructor() { this.task = null this.status = 'closed' // closed | connecting | open this.url = '' this.manualClose = false this.reconnectCount = 0 this.heartbeatTimer = null this.reconnectTimer = null this.messageHandler = {} } connect(url) { if (this.status === 'connecting' || this.status === 'open') return this.url = url this.manualClose = false this.status = 'connecting' this.task = uni.connectSocket({ url, complete: () => {} }) this.task.onOpen(() => this.handleOpen()) this.task.onMessage((res) => this.handleMessage(res.data)) this.task.onError(() => this.handleError()) this.task.onClose(() => this.handleClose()) } } const wsManager = new WebSocketManager() export default wsManager

这个单例类先把骨架立住，下面几个小节逐步往里面填心跳、重连、消息路由的逻辑。

3.2 心跳机制：不心跳，迟早被服务端断开

很多人以为 WebSocket 连上之后，连接就一直在那躺着，永远可用。实际上微信小程序也好、后端网关也好，往往都会对空闲连接做超时清理。下沉到移动网络里，运营商 NAT 网关也可能把长时间没有数据交互的连接给静默回收。

所谓静默回收非常阴险：服务端和网络设备把连接断掉之后，客户端短时间内感知不到，因为没有任何数据包触发送达错误，你只有真正发一条消息才发现对方失联了。为了及时感知连接是否健康，就要定时发送心跳包。

一个常规的设计是：连接打开成功后，每 30 秒发送一次心跳消息，消息格式用{ type: 'heartbeat', payload: { timestamp: Date.now() } }，服务端收到后回一个 pong。如果连续 3 次心跳没有收到任何响应，就认为连接已经失效，主动重连。

handleOpen() { this.status = 'open' this.reconnectCount = 0 this.startHeartbeat() this.flushQueue() } startHeartbeat() { this.stopHeartbeat() this.heartbeatTimer = setInterval(() => { if (this.status !== 'open') return this.send({ type: 'heartbeat', payload: { timestamp: Date.now() } }) }, 30000) } stopHeartbeat() { if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer) this.heartbeatTimer = null } }

心跳间隔设多长要结合服务端配置来定。如果服务端空闲超时阈值是 60 秒，你心跳间隔至少要比 60 秒小一半，给网络抖动留出容错空间。我常用 30 秒，性能和服务端压力都平衡。

这里有一个容易忽略的细节：小程序切到后台后，定时器会被系统挂起，回前台瞬间心跳定时器才恢复。接上当时的状态检查逻辑会更好。

3.3 断线重连：指数退避是基本素养

连接断了怎么办？最简单的做法是在 onClose 里重新调用 connect。但是这里有个大坑：连不上就马上重试，再失败再马上重试，形成“重连风暴”。服务端如果正在重启，这种风暴会把它彻底压垮。

业界公认的做法是指数退避：第一次重连等 1 秒，第二次等 2 秒，第三次等 4 秒，以此类推，上限通常卡在 30 秒或 60 秒。这个策略的原理是：如果服务端是临时故障，前几次很快就能恢复；如果服务端长时间不可用，你频繁重连只会给自己和服务端添乱，不如把节奏慢下来。

scheduleReconnect() { if (this.manualClose) return // 2^n 秒退避，上限 60 秒 const delay = Math.min(60000, 1000 * Math.pow(2, this.reconnectCount)) this.reconnectCount++ this.reconnectTimer = setTimeout(() => { this.connect(this.url) }, delay) }

有个细节值得细说：指数退避如果真按固定公式走，多个客户端会在同一时间点一起重连，服务端依然可能被打满。所以更稳妥的做法是在计算出来的延迟上叠加一个随机抖动（jitter），比如计算结果的 50% 到 100% 之间随机取一个值。这里用 1000 乘2^n得到的数字再乘以0.5 + Math.random() * 0.5，可以显著打散重连请求。

除了定时重连，还要配合网络状态监听。小程序提供uni.onNetworkStatusChange，当网络从断开恢复到可用时，立刻判断当前 WebSocket 是否为 open，如果不是就清空退避计数并马上重连。这样用户从电梯里出来、从地下车库回到地面时，连接能快速恢复，不用等退避计时器慢慢倒计时。

uni.onNetworkStatusChange((res) => { if (res.isConnected && this.status !== 'open') { this.reconnectCount = 0 this.connect(this.url) } })

3.4 消息协议、路由与补偿

连接稳定了，下一步要解决的是消息怎么组织、怎么分发。WebSocket 是一条管道，所有业务消息都从这条管道里走，如果不定义协议，前端拿到一堆字符串根本分不清谁是谁。

我习惯用 JSON 统一消息体，最外层固定三个字段：type 用来标识业务类型，payload 放数据，msgId 放消息唯一序号：

{ "type": "chat.message", "msgId": "20241201103201-001", "payload": { "from": "user_123", "content": "你好" } }

前端收到消息后，先解析，再根据 type 把消息分发给不同的处理函数。

handleMessage(data) { let msg try { msg = JSON.parse(data) } catch (e) { console.warn('消息解析失败', data) return } const handlers = this.messageHandler[msg.type] || [] handlers.forEach((fn) => fn(msg.payload, msg)) }

给消息加上 msgId 还有个好处是幂等去重。弱网环境下，消息重发是常态，服务端可能把同一条消息送来两次，前端如果不去重，用户就会看到重复消息。用一个数组或 Set 缓存最近处理过的 msgId，重复的直接丢掉，这个处理在业务上非常必要。

连接断开期间，用户产生的消息发送会失败。比较合理的做法是维护一个待发送队列：发送时如果连接不在 open 状态，就把消息暂存到队列里，等连接恢复（onOpen 之后）把队列顺序补发。这个机制的细节是补发时机要配合登录态校验，确保连接重连后用户身份仍然有效，不然消息补发了也可能被服务端拒收。

4. 实战里的连接生命周期管理

4.1 App 和页面的协作关系

WebSocket 连接应该什么时候建立？没有严格标准，取决于业务需要。如果小程序是一个打开就要实时收消息的工具，那可以在 App.vue 的onLaunch里初始化连接；如果只有进入特定页面才需要连接，可以在那个页面的onLoad时连接。我个人的习惯是：尽量在进入核心业务页时再建连，而不是启动小程序就无脑连，毕竟连接和心跳都有资源消耗。

真正麻烦的地方在于页面和连接之间的协作。假设首页和聊天页都需要收消息，两个页面都用同一个单例来注册消息回调，页面切换时如果不做释放，同样一份消息回调会被注册两次，产生重复处理。

我的做法是：每个页面在onLoad时注册自己关心的消息类型，在onUnload时解除注册，连接本身不关闭。消息分发器负责根据当前页面的注册情况进行派发，页面消失了，注册自然移除，消息不进该页面。

// 页面内 onLoad() { wsManager.subscribe('chat.message', this.handleChatMessage) } onUnload() { wsManager.unsubscribe('chat.message', this.handleChatMessage) }

subscribe 底层就是在 messageHandler 数组里 push，unsubscribe 就是 filter 掉对应函数，逻辑简单，却能避免大量难查的重复消息 bug。

4.2 小程序前后台切换的坑

微信小程序有一套前后台生命周期：用户按 Home 键切到后台，小程序会触发onHide；用户重新点进来，触发onShow。这套生命周期的关键影响在于：小程序退到后台大约 5 秒后会被系统挂起，JavaScript 定时器停摆，WebSocket 连接虽然不一定会立刻断开，但也不能保证一直可用。

所以严谨的做法是：在onHide记录离开时间戳，在onShow回来之后做两件事。第一，用当前时间减去离开时间戳，如果间隔超过心跳阈值，立即检查连接状态；第二，判断连接状态，如果已经处于 closed 或 connecting，触发一次重连。

onShow() { const gap = Date.now() - this.hideTimestamp if (gap > 30000) { // 先发一次探测消息，看看连接是不是活着 wsManager.send({ type: 'ping', payload: { ts: Date.now() } }) // 如果连接已断，wm 内部会自动触发重连 } } onHide() { this.hideTimestamp = Date.now() }

有的方案是在onShow里无脑 close 再重连，虽然也能恢复，但会造成消息短暂丢失。更温和的方式是让心跳机制去判断，如果连接真的死了，onError 或 onClose 会自然触发重连流程。

4.3 资源清理与内存安全

WebSocket 封装类容易出内存问题，主要体现在三个地方。定时器没有清理，页面或 App 销毁后代码依然在跑；注册过的消息回调没有解绑，造成对象无法被回收；连接关闭后实例引用还留在全局，导致重新连接时出现状态错乱。

我一般在关闭连接的地方集中做清理：

closeSocket() { this.manualClose = true this.stopHeartbeat() if (this.reconnectTimer) { clearTimeout(this.reconnectTimer) this.reconnectTimer = null } if (this.task) { this.task.close({ code: 1000, reason: 'user close' }) this.task = null } this.status = 'closed' }

manualClose 这个标记很关键。它用来区分“用户主动关闭”和“异常断开”：只有异常断开才走重连逻辑，用户主动关闭的情况下还要不停重连，那才是真的灾难。

5. 常见问题排查速查与避坑清单

5.1 常见问题速查表

我把项目里真实踩过的坑整理成一张速查表，建议收藏：

5.2 排查思路的顺序

遇到 WebSocket 问题，我建议大家按顺序排查，不要一上来就怀疑代码逻辑。第一步，先看微信开发者工具的 Network 面板，确认 WebSocket 那条连接是否真的建立成功，握手状态是不是 101。第二步，看服务端日志，确认有没有收到心跳包和上行消息。第三步，在小程序端打点日志，把连接状态机的变化记录下来：何时 open、何时 close、何时 error、何时重连，配合时间线比照。

很多看似玄学的问题，放到时间线上一看就清楚了。比如某次“连接频繁断开”，打点日志显示每分钟 open/close 交替一次，再对照服务端配置的空闲超时 60 秒，基本就是心跳间隔太长或心跳包格式不被服务端识别导致的，一改就好。

5.3 性能优化与工程保障

WebSocket 消息频率高的时候，小程序性能问题会很突出。一个最常见的错误是每收到一条 WebSocket 消息，就把整页数据 setData 一次。小程序的数据更新走的是逻辑层到渲染层的桥接通道，高频大对象更新直接导致页面掉帧。

性能优化的思路是“合并和分片”。消息频率高时，把多条消息在数组里累积，定时批量更新视图；消息体大时，服务端做分片传输，客户端组装，避免一次 setData 传输超大 JSON。更重要的是，只更新视图真正用到的数据字段，不要动不动塞一整个对象。

另一个容易被忽略的点是日志。生产环境不要打印全量消息内容，尤其不要打印包含用户敏感信息的完整 JSON。我在正式环境只打消息类型和消息长度，出问题时再去临时开完整日志，这样既能定位问题，又不至于把用户聊天记录写得到处都是。

最后再说说连接数的工程约束：微信小程序环境对 WebSocket 连接数是有限制的，建议全局只保留一条连接。业务上无论有多少种实时消息，都走这一条连接，用消息 type 做路由。某次项目里同事为了省事，在三个页面各开了一条连接，结果上线后总掉线，排查半天发现是连接数超限，服务端把多余的连接踢掉了。全局单例连接这件事，不是风格问题，是避坑问题。

这个 WebSocket 方案我还有几个可以继续深挖的方向，比如结合定时推送做离线消息补偿、服务端推送消息的批量聚合策略、以及把连接状态做成全局响应式数据供任意组件实时感知。这些都是后面实战中值得逐步完善的部分。