UniApp WebSocket工具类封装：实现稳定实时通信与自动重连

1. 项目概述：为什么需要一个WebSocket工具类？

在UniApp开发APP时，但凡涉及到实时数据交互，比如聊天室、实时通知、协同编辑、在线游戏或者股票行情，WebSocket几乎是绕不开的技术。很多新手朋友拿到需求，第一反应可能就是直接在每个页面里new WebSocket()，然后写一堆onOpen、onMessage、onError、onClose的回调。这样做一两个页面还好，一旦项目稍微复杂点，问题就全暴露出来了：连接管理混乱，可能一个页面关了连接没关，另一个页面又新建一个；消息监听器到处都是，难以维护；重连逻辑写得到处都是，既不优雅也容易出Bug。

我自己在多个UniApp的APP项目里踩过这些坑之后，总结下来，封装一个统一的WebSocket工具类不是“锦上添花”，而是“雪中送炭”。它的核心价值在于统一管理、降低耦合、提升健壮性。通过一个工具类，我们可以把连接的建立、维护、重连、消息的发送与分发、以及错误处理都收敛到一处。页面组件只需要关心“发送什么消息”和“接收消息后更新什么UI”，完全不用操心底层连接的状态。这不仅能极大提升开发效率，也让后期维护和调试变得清晰简单。尤其是在APP端，网络环境复杂（移动网络切换、应用退到后台），一个健壮的工具类能帮你省去大量处理异常状态的时间。

2. 核心需求与设计思路拆解

在动手写代码之前，我们先别急着打开编辑器。一个好的设计思路，能让我们后续的编码事半功倍，避免反复重构。基于常见的业务场景，我梳理了一个WebSocket工具类需要满足的几个核心需求。

2.1 核心需求解析

1. 单一连接实例：整个应用应该只有一个WebSocket连接实例（单例模式），避免资源浪费和连接冲突。无论从哪个页面调用，操作的都是同一个连接。
2. 自动重连机制：网络不稳定是移动端的常态。连接意外断开后，工具类应能自动尝试重连，并具备可配置的重连策略（如延迟时间、最大重试次数）。
3. 消息统一管理：能够方便地发送消息，并灵活地订阅/监听特定类型的消息。页面组件可以注册对某个“消息类型”或“事件”的监听器，当服务器推送对应消息时，自动触发回调。
4. 连接状态管理：需要对外暴露清晰的连接状态（如connecting,open,closing,closed），方便UI层根据状态展示不同的界面（比如连接中显示Loading，断开显示重连按钮）。
5. 心跳保活：为了防止长时间无数据交互导致连接被运营商或服务器网关意外断开，需要实现心跳机制，定期向服务器发送Ping消息。
6. 良好的错误处理与日志：连接错误、消息格式错误等都需要有统一的处理入口和日志记录，便于问题排查。
7. 与UniApp生命周期协同：需要考虑APP切换到后台时，是否维持连接；以及页面卸载时，如何清理该页面注册的监听器，避免内存泄漏。

2.2 方案选型与设计考量

基于以上需求，我们的设计思路就清晰了：

• 类结构：采用ES6的Class来封装，结构清晰，易于维护。
• 单例模式：通过模块导出一个唯一的实例，确保全局唯一。
• 事件中心：借鉴发布-订阅模式，内部维护一个事件映射表，用于管理不同类型的消息监听器。这是实现消息统一分发的关键。
• 状态机：使用一个内部变量_status来标识当前连接状态，并提供获取状态的方法。
• 配置化：将服务器地址、重连策略、心跳间隔等参数设计为可配置项，通过构造函数或初始化方法传入，提高工具类的灵活性。

为什么不直接用一些现成的库？对于UniApp APP端，原生uni.connectSocketAPI已经足够底层和稳定，封装自己的工具类可以做到最轻量、最贴合自身业务，没有冗余依赖，也方便进行深度定制。

3. WebSocket工具类核心实现详解

接下来，我们进入核心的代码实现环节。我会逐块解释代码，并说明为什么这么写，以及需要注意的坑。

3.1 类定义与基础属性

首先，我们定义类的骨架和必要的内部状态。

// websocket.js export default class WebSocketClient { constructor(options = {}) { // 合并默认配置与用户配置 this.config = Object.assign({ url: '', // 连接地址，必须 reconnectLimit: 5, // 最大重连次数 reconnectInterval: 3000, // 重连间隔(ms) heartInterval: 30000, // 心跳间隔(ms) heartMsg: 'ping', // 心跳消息内容 }, options); // WebSocket 连接任务（uni-app 返回的 socketTask 对象） this.socketTask = null; // 当前连接状态 this._status = 'closed'; // 'connecting', 'open', 'closing', 'closed' // 重连尝试次数计数器 this.reconnectCount = 0; // 心跳定时器ID this.heartBeatTimer = null; // 重连定时器ID this.reconnectTimer = null; // 事件监听器映射表 { eventType: [callback1, callback2, ...] } this.eventMap = new Map(); // 标记是否主动关闭（用于区分异常断开和主动断开） this.isCustomClose = false; } }

关键点解析：

• socketTask: 这是UniApp WebSocket API的核心。uni.connectSocket返回的是一个SocketTask对象，后续所有的发送、监听、关闭操作都基于它，而不是浏览器中标准的WebSocket实例。务必保存好这个引用。
• _status: 我们自定义了四个状态，比原生API更精细，方便业务逻辑判断。
• eventMap: 使用Map来存储事件类型和对应的回调函数数组，这是实现发布-订阅模式的基础。
• isCustomClose: 这是一个非常重要的标志位。用来判断连接断开是由于网络问题还是我们主动调用close方法。只有非主动关闭时，才需要触发自动重连逻辑。

3.2 连接建立与事件监听

连接建立不是简单调用uni.connectSocket就完了，需要妥善设置事件监听。

connect() { if (this._status !== 'closed' && this.socketTask) { console.warn('WebSocket连接已存在或正在连接中'); return; } this._status = 'connecting'; this.isCustomClose = false; // 开始连接时，重置为非主动关闭标志 // 1. 创建连接 this.socketTask = uni.connectSocket({ url: this.config.url, success: () => { console.log('WebSocket连接创建成功'); }, fail: (err) => { console.error('WebSocket连接创建失败', err); this._handleReconnect(); // 创建失败也触发重连 } }); // 2. 监听WebSocket事件 this._watchSocketEvents(); } _watchSocketEvents() { if (!this.socketTask) return; // 监听连接打开 this.socketTask.onOpen(() => { console.log('WebSocket连接已打开'); this._status = 'open'; this.reconnectCount = 0; // 连接成功，重置重连计数器 this.emit('open'); // 触发自定义open事件 this._startHeartBeat(); // 开启心跳 }); // 监听收到服务器消息 this.socketTask.onMessage((res) => { // 这里可能收到心跳回复，也可能收到业务消息 if (res.data === 'pong' || res.data === this.config.heartMsg) { // 收到心跳回复，连接正常，可重置心跳或不做处理 console.log('收到心跳回复'); return; } // 处理业务消息 try { const data = typeof res.data === 'string' ? JSON.parse(res.data) : res.data; this.emit('message', data); // 触发自定义message事件，并传递数据 // 如果消息有特定类型字段，也可以触发特定事件，例如：this.emit(data.type, data) } catch (e) { console.error('消息解析失败:', e, res.data); this.emit('error', new Error('消息格式错误')); } }); // 监听连接错误 this.socketTask.onError((err) => { console.error('WebSocket连接发生错误', err); this._status = 'closed'; this.emit('error', err); this._handleReconnect(); // 错误时触发重连 }); // 监听连接关闭 this.socketTask.onClose((res) => { console.log('WebSocket连接已关闭', res); this._status = 'closed'; this.socketTask = null; // 清理任务引用 this._stopHeartBeat(); // 停止心跳 // 如果不是主动关闭，则尝试重连 if (!this.isCustomClose) { this.emit('close', res); this._handleReconnect(); } else { // 主动关闭，触发自定义close事件，但不重连 this.emit('custom-close', res); } }); }

实操心得与避坑指南：

1. onOpen回调时机：在UniApp中，onOpen回调代表连接已经建立，可以开始发送数据。但请注意，uni.connectSocket的success回调仅表示创建连接的任务成功，不代表连接已建立。真正的连接成功是在socketTask.onOpen里。
2. 消息格式处理：服务器返回的消息可能是JSON字符串，也可能是纯文本。工具类里做了简单的JSON.parse尝试，更健壮的做法是让业务层根据与后台的约定自行解析。这里触发一个通用的'message'事件，将原始数据抛出去。
3. 区分关闭原因：onClose回调是重连逻辑的触发点。必须依靠isCustomClose标志位来区分，否则用户手动断开连接后，工具类又会傻傻地不断重连，造成困扰。

3.3 消息发送、事件订阅与取消订阅

这是工具类与业务页面交互的主要接口，必须设计得简单易用。

// 发送消息 send(data) { if (this._status !== 'open') { console.error('WebSocket未连接，消息发送失败'); this.emit('error', new Error('WebSocket is not connected')); return false; } const msg = typeof data === 'object' ? JSON.stringify(data) : data; this.socketTask.send({ data: msg, success: () => { // console.log('消息发送成功'); }, fail: (err) => { console.error('消息发送失败', err); this.emit('error', err); } }); return true; } // 订阅事件（添加消息监听器） on(event, callback) { if (typeof callback !== 'function') { throw new Error('回调函数必须是一个Function'); } if (!this.eventMap.has(event)) { this.eventMap.set(event, []); } this.eventMap.get(event).push(callback); } // 取消订阅（移除消息监听器） off(event, callback) { if (!this.eventMap.has(event)) return; const callbacks = this.eventMap.get(event); const index = callbacks.indexOf(callback); if (index > -1) { callbacks.splice(index, 1); } // 如果该事件没有回调了，清理空间 if (callbacks.length === 0) { this.eventMap.delete(event); } } // 触发事件（内部方法，用于消息分发） emit(event, data) { if (this.eventMap.has(event)) { this.eventMap.get(event).forEach(callback => { try { callback(data); } catch (e) { console.error(`执行事件 ${event} 的回调时发生错误:`, e); } }); } }

注意事项：

• 内存泄漏：on和off必须成对使用。特别是在Vue/UniApp页面中，一定要在页面的onUnload生命周期里，取消注册当前页面所有的事件监听器。否则，页面销毁后，回调函数依然被工具类引用，导致内存无法释放。
• 错误处理：emit方法内部对每个回调执行进行了try-catch包裹，防止某个监听器的错误导致整个消息分发链中断。

3.4 自动重连与心跳保活机制

这两个是保障连接稳定的核心功能，逻辑相对独立。

// 处理重连 _handleReconnect() { // 主动关闭的不重连 if (this.isCustomClose) return; // 清除之前的重连定时器 this._clearReconnectTimer(); // 超过重连次数限制 if (this.reconnectCount >= this.config.reconnectLimit) { console.error(`WebSocket重连次数超过限制(${this.config.reconnectLimit})，停止重连`); this.emit('reconnect-failed'); return; } // 记录重连次数 this.reconnectCount++; console.log(`第${this.reconnectCount}次尝试重连...`); // 设置重连定时器 this.reconnectTimer = setTimeout(() => { this.connect(); }, this.config.reconnectInterval); } _clearReconnectTimer() { if (this.reconnectTimer) { clearTimeout(this.reconnectTimer); this.reconnectTimer = null; } } // 开始心跳检测 _startHeartBeat() { console.log('启动心跳检测'); this._stopHeartBeat(); // 开始前先清除旧的 this.heartBeatTimer = setInterval(() => { if (this._status === 'open') { this.send(this.config.heartMsg); // 发送心跳 console.log('发送心跳:', this.config.heartMsg); } }, this.config.heartInterval); } _stopHeartBeat() { if (this.heartBeatTimer) { clearInterval(this.heartBeatTimer); this.heartBeatTimer = null; } }

核心逻辑与参数选择：

• 指数退避：上述重连策略是固定间隔。更高级的策略是“指数退避”，即每次重连间隔逐渐增加（例如 1s, 2s, 4s, 8s...），避免在服务器临时故障时疯狂重连。你可以修改_handleReconnect中的延迟逻辑来实现。
• 心跳内容：心跳消息heartMsg需要与后端协商好。可以是简单的字符串"ping"，也可以是一个特定的JSON结构，如{type: 'heartbeat'}。后端收到后，通常需要回复一个"pong"或确认消息。我们的onMessage里已经做了简单判断。
• 心跳间隔：heartInterval设置为30秒是一个常见的折中选择。太短会增加不必要的流量和服务器压力，太长则可能让中间网关认为连接已空闲而断开。需要根据实际网络环境和服务器配置调整。

3.5 连接关闭与资源清理

提供可控的关闭方法，并清理所有内部资源。

// 关闭连接 close() { this.isCustomClose = true; // 标记为主动关闭 this._clearReconnectTimer(); // 清除重连定时器 this._stopHeartBeat(); // 停止心跳 this.eventMap.clear(); // 清空所有事件监听（根据业务需求决定，也可不清） if (this.socketTask && this._status !== 'closed') { this.socketTask.close({}); this.socketTask = null; } this._status = 'closed'; console.log('WebSocket连接已主动关闭'); } // 获取当前状态 getStatus() { return this._status; }

重要提示：close()方法中的this.eventMap.clear()会清空所有页面注册的监听器。如果你希望下次connect时这些监听依然有效，可以移除这行。但更常见的做法是，由各个页面自己管理监听器的生命周期（在onLoad订阅，在onUnload取消订阅），工具类只提供关闭连接本身的功能。

4. 在UniApp项目中集成与使用

工具类写好了，接下来就是在项目中实际使用了。我们创建一个单例，并在页面中调用。

4.1 创建单例并导出

新建一个utils/websocket.js文件，将上述所有代码放入，并在文件末尾创建并导出一个实例。

// utils/websocket.js // ... 上面是完整的WebSocketClient类定义 // 创建全局唯一的WebSocket实例 const wsClient = new WebSocketClient({ url: 'wss://your-websocket-server.com/ws', // 你的WebSocket服务器地址 reconnectLimit: 5, reconnectInterval: 3000, }); // 默认不自动连接，由页面在需要时调用 connect() // wsClient.connect(); export default wsClient;

4.2 在Vue页面/组件中使用

我们来看一个简单的聊天页面示例。

<template> <view class="content"> <view class="status">连接状态: {{ status }}</view> <scroll-view scroll-y class="message-list"> <view v-for="(msg, index) in messages" :key="index" class="message">{{ msg }}</view> </scroll-view> <view class="input-area"> <input v-model="inputMsg" @confirm="sendMessage" placeholder="输入消息..." /> <button @tap="sendMessage">发送</button> <button @tap="toggleConnection">{{ status === 'open' ? '断开' : '连接' }}</button> </view> </view> </template> <script> import wsClient from '@/utils/websocket.js'; export default { data() { return { status: 'closed', messages: [], inputMsg: '' }; }, onLoad() { this.initWebSocket(); }, onUnload() { // 页面卸载时，务必取消事件监听！ wsClient.off('open', this.handleOpen); wsClient.off('message', this.handleMessage); wsClient.off('error', this.handleError); wsClient.off('close', this.handleClose); // 注意：这里不调用 wsClient.close()，因为其他页面可能还在用这个连接。 // 除非你确定这个页面是连接的唯一使用者，或者APP要退出了。 }, methods: { initWebSocket() { // 订阅事件 wsClient.on('open', this.handleOpen); wsClient.on('message', this.handleMessage); wsClient.on('error', this.handleError); wsClient.on('close', this.handleClose); // 可以在这里判断状态，如果未连接则自动连接 if (wsClient.getStatus() !== 'open' && wsClient.getStatus() !== 'connecting') { wsClient.connect(); } }, handleOpen() { uni.showToast({ title: '连接成功', icon: 'success' }); this.status = wsClient.getStatus(); this.messages.push('[系统] 连接已建立'); }, handleMessage(data) { // 这里处理业务消息，假设服务器返回 { type: 'chat', content: 'Hello' } console.log('收到消息:', data); this.messages.push(`[对方] ${data.content}`); }, handleError(err) { console.error('WebSocket错误:', err); uni.showToast({ title: `连接错误: ${err.message || err.errMsg}`, icon: 'none' }); this.status = wsClient.getStatus(); }, handleClose(res) { console.log('连接关闭:', res); this.messages.push('[系统] 连接已断开，正在尝试重连...'); this.status = wsClient.getStatus(); }, sendMessage() { if (!this.inputMsg.trim()) return; const msg = { type: 'chat', content: this.inputMsg }; const success = wsClient.send(msg); if (success) { this.messages.push(`[我] ${this.inputMsg}`); this.inputMsg = ''; } }, toggleConnection() { if (wsClient.getStatus() === 'open') { wsClient.close(); // 主动关闭 this.status = 'closed'; this.messages.push('[系统] 连接已手动关闭'); } else { wsClient.connect(); } } } }; </script>

使用要点总结：

1. 生命周期绑定：一定要在onLoad或onShow中订阅事件，在onUnload中取消订阅。这是防止内存泄漏的关键。
2. 状态驱动UI：通过wsClient.getStatus()获取状态并更新页面，给用户明确的反馈。
3. 连接时机：示例中在initWebSocket里判断状态并决定是否自动连接。你也可以在APP启动时（App.vue的onLaunch）就建立连接，全局使用。这取决于你的业务场景——如果只有少数页面需要WebSocket，按需连接更省资源；如果整个APP都依赖实时数据，则适合全局连接。
4. 消息格式：示例中发送和接收的都是JSON对象，并假设有一个type字段。在实际项目中，你需要和后端工程师定义一套双方认可的消息协议。

5. 进阶优化与常见问题排查

一个基础的工具有了，但在生产环境中，我们还需要考虑更多。

5.1 进阶优化点

1. 消息队列（发送缓冲）：在连接未就绪（status !== 'open'）时，调用send会失败。可以引入一个消息队列，将发送失败或连接中的消息缓存起来，等连接open后自动按序发送。这对于确保关键消息不丢失很有用。
2. 重连策略升级：实现前文提到的“指数退避”算法，并考虑在网络恢复（通过uni.onNetworkStatusChange监听）后立即尝试重连。
3. 连接状态持久化：可以将连接状态（如_status,reconnectCount）通过Vuex或Pinia管理，方便多个组件共享和响应状态变化。
4. 与App生命周期联动：在App.vue中监听应用进入后台（onHide）和前台（onShow）。进入后台时，可以主动关闭WebSocket或停止心跳以节省电量；回到前台时，检查并恢复连接。

   // App.vue export default { onHide() { // 可选：断开连接或停止心跳 // import wsClient from '@/utils/websocket'; // wsClient.close(); }, onShow() { // 可选：恢复连接 // if (wsClient.getStatus() === 'closed' && !wsClient.isCustomClose) { // wsClient.connect(); // } } }

5. 支持多协议：你的工具类目前处理的是JSON。如果后端消息格式是Protocol Buffers或其他二进制协议，需要在onMessage和send方法中增加相应的编解码逻辑。

5.2 常见问题排查实录

在实际开发中，你肯定会遇到各种问题。下面是我踩过的一些坑和解决方案：

最后，再分享一个调试小技巧：在开发阶段，可以将工具类中的console.log都打开，并给日志加上前缀，如[WS]，这样在调试器控制台可以快速过滤出所有WebSocket相关的日志，方便跟踪连接、消息、重连的整个生命周期。上线前，可以通过环境变量或构建配置来移除这些日志。