在前端開發中，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();
適用場景
實時聊天系統（如客服對話、直播間彈幕）
通知中心（如新消息提醒、系統公告推送）
實時數據監控（如儀表盤數據實時更新）
協同編輯工具（多人協作場景下的狀態同步）
游戲實時交互（低延遲的游戲狀態同步）
