🔥 轻松管理 WebSocket 连接！easy-websocket-client

在前端开发中，WebSocket 是实现实时通信的核心技术，但原生 WebSocket 的连接管理（如断连重连、心跳维护、事件监听）往往需要编写大量重复代码。今天给大家分享一个自己开发的 WebSocket 连接管理库 —— easy-websocket-client，帮你一站式解决连接管理难题，专注业务逻辑开发！

🚀 核心优势

• 极简集成：一行代码创建连接，内置常用配置项，开箱即用。
• 智能重连：自动处理断连重连，支持最大重连次数和间隔配置。
• 心跳机制：可自定义心跳消息和间隔，保持连接活性。
• 灵活事件：支持连接打开、关闭、消息接收、错误等全生命周期回调。
• 单例模式：轻松实现全局唯一连接，避免重复创建和内存泄漏。
• TypeScript 支持：全程 TypeScript 开发，提供完善类型定义，智能提示更友好。

🛠 主要功能特性

1. 自动重连机制

• reconnectInterval：重连间隔
• maxReconnectAttempts：最大重连次数
• 断连后自动发起重连，达到最大次数后停止尝试
• 适用于网络不稳定场景，减少手动处理重连的繁琐代码

2. 可定制化心跳

• heartbeatMessage：自定义心跳消息内容（支持字符串或对象）
• heartbeatInterval：心跳发送间隔
• 自动检测服务端响应，心跳失败时触发重连

3. 全生命周期事件回调

• onOpen：连接成功时触发
• onClose：连接关闭时触发（携带 CloseEvent 参数）
• onMessage：接收消息时触发（自动解析文本/二进制数据）
• onError：连接报错时触发（捕获网络错误等异常）

4. 单例模式支持

• 装饰器方式：通过 @singleton 装饰器快速实现单例类
• 高阶函数方式：兼容不支持装饰器的环境，通过 singleton 函数包裹
• 刷新页面自动恢复连接，避免多页面重复创建

📦 快速上手

安装

# 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();

📌 适用场景

• 实时聊天系统（如客服对话、直播间弹幕）
• 通知中心（如新消息提醒、系统公告推送）
• 实时数据监控（如仪表盘数据实时更新）
• 协同编辑工具（多人协作场景下的状态同步）
• 游戏实时交互（低延迟的游戏状态同步）

🧰 技术栈说明

• 基于原生 WebSocket 封装，支持浏览器和 Node.js（通过 ws 库）
• 使用 TypeScript 开发，提供完整类型定义
• 支持 UMD 规范，可直接通过 <script> 标签引入
• 内置代码检查（ESLint）和单元测试（Jest），保证稳定性

📚 项目地址

• GitHub 仓库：github.com/JsonLee12138/easy-webso...
• NPM 包：www.npmjs.com/package/easy-websock...

如果觉得这个库对你有帮助，欢迎 Star ⭐ 支持！也欢迎提 Issue 或 PR 一起完善~
有任何使用问题或需求，欢迎在评论区交流，我会及时回复 😊

本作品采用《CC 协议》，转载必须注明作者和本文链接