在前端开发中，WebSocket 是实现实时通信的核心技术，但原生 WebSocket 的连接管理（如断连重连、心跳维护、事件监听）往往需要编写大量重复代码。今天给大家分享一个好用的 WebSocket 连接管理库 —— easy-websocket-client，功能都已经封装好，配置一下就好了。

主要功能特性

1. 自动重连机制

reconnectInterval：重连间隔

maxReconnectAttempts：最大重连次数

断连后自动发起重连，达到最大次数后停止尝试

适用于网络不稳定场景，减少手动处理重连的繁琐代码

2. 可定制化心跳

heartbeatMessage：自定义心跳消息内容（支持字符串或对象）

heartbeatInterval：心跳发送间隔

自动检测服务端响应，心跳失败时触发重连

3. 全生命周期事件回调

onOpen：连接成功时触发

onClose：连接关闭时触发（携带 CloseEvent 参数）

onMessage：接收消息时触发（自动解析文本 / 二进制数据）

onError：连接报错时触发（捕获网络错误等异常）

快速上手

安装

# npm
npm install easy-websocket-client# yarn
yarn add easy-websocket-client# pnpm
pnpm add easy-websocket-client

基本使用

import WebSocketClient from 'easy-websocket-client';// 创建连接实例
const client = new WebSocketClient('wss://example.com/socket', {showLog: true,                  // 开启控制台日志reconnectInterval: 2000,        // 重连间隔 2 秒heartbeatInterval: 10000,       // 心跳间隔 10 秒heartbeatMessage: 'ping',       // 心跳消息maxReconnectAttempts: 5,        // 最大重连次数onOpen: () => console.log('连接已打开'),onClose: (e) => console.log('连接关闭', e),onMessage: (message) => console.log('收到消息', message),onError: (error) => console.error('连接错误', error),
});// 发起连接
client.connect();// 发送消息
client.send('Hello WebSocket!');// 关闭连接
client.close();

单例模式实现（装饰器方式）

import { singleton } from 'easy-websocket-client';interface Message {type: string;data: any;
}@singleton
class MyWebSocketClient extends WebSocketClient<Message> {constructor() {// 动态生成连接地址（支持开发/生产环境区分）const baseURL = import.meta.env.DEV? `ws://${import.meta.env.VITE_WS_HOST}:${import.meta.env.VITE_PORT}/ws`: import.meta.env.VITE_API_URL;super(baseURL, {heartbeatMessage: { type: 'HEARTBEAT', textMsg: 'ping' }, // 对象类型心跳消息heartbeatInterval: 10000,maxReconnectAttempts: 3,connectResend: true, // 重连后自动重发未完成的消息onMessage(data) {console.log('业务消息处理:', data);},});this.connect();}// 支持手动关闭并重置单例public close = () => {super.close();MyWebSocketClient.reset(); // 重置单例实例};
}// 全局唯一实例
const clientInstance = new MyWebSocketClient();