websocket-client-plus

一个支持自动重连与心跳检测的 WebSocket 客户端，适用于需要稳定长连接的前端应用。

✨ 功能特点

• 封装原生 WebSocket，支持断线自动重连
• 内置心跳检测机制，防止连接意外断开
• 支持单例模式，避免重复连接
• 简洁的事件驱动 API（支持 on / off / emit 方法）
• 类型安全、零依赖、易于扩展
• 适用于实时数据推送、消息系统、状态同步等场景

📦 安装

# 使用 pnpm
pnpm add websocket-client-plus

# 使用 npm
npm install websocket-client-plus

# 使用 yarn
yarn add websocket-client-plus

🔧 使用示例

import SocketClient from 'websocket-client-plus'

const client = SocketClient.getInstance('wss://example.com/ws', {
  heartbeatInterval: 5000,
  maxReconnectAttempts: 5
})

client.on('channel-open', () => {
  console.log('连接已建立')
  client.send('hello server')
})

client.on('channel-message', (msg) => {
  console.log('收到消息:', msg)
})

client.on('channel-error', (err) => {
  console.error('连接错误:', err)
})

client.on('channel-close', () => {
  console.log('连接已关闭')
})

client.on('state-change', (state) => {
  console.log('状态变更:', state)
})

🧩 支持的事件

| 事件名称 | 描述 | | --------------------- | ------------------------------ | | channel-open | WebSocket 连接成功建立后触发 | | channel-message | 每收到一条服务端消息时触发 | | channel-error | 连接错误时触发，包含异常详情 | | channel-close | 连接被关闭时触发 | | state-change | 连接状态变更时触发（如 CONNECTING、OPEN 等） | | reconnect-exhausted | 超出最大重连次数后触发，停止继续重连 |

⚙️ 可选配置项

通过构造函数或 getInstance() 的第二个参数传入：

| 配置项 | 类型 | 默认值 | 描述 | | ---------------------- | -------- | -------- | ------------- | | baseRetryDelay | number | 2000 | 初始重连延迟（ms） | | maxRetryDelay | number | 60000 | 最大重连延迟（ms） | | maxReconnectAttempts | number | 10 | 最大自动重连尝试次数 | | heartbeatInterval | number | 5000 | 心跳发送间隔（ms） | | pingMessage | string | 'ping' | 发送到服务端的心跳消息内容 | | pongMessage | string | 'pong' | 服务端响应的心跳消息内容 |

🛠️ API 文档

SocketClient.getInstance(url: string, options?: SocketClientOptions): SocketClient

创建并获取 WebSocket 单例客户端。

send(message: string): void

发送字符串消息。

on(eventName: string, handler: (...args: any[]) => void): void

注册事件监听器。

off(eventName: string, handler?: (...args: any[]) => void): void

移除事件监听器。

destroy(): void

销毁客户端，断开连接并清除资源。

🧪 示例场景

• 🧠 AI 聊天：基于 WebSocket 实现的实时多轮对话
• 📡 实时看板：服务端推送状态/指标数据更新
• 🎮 多人协作：白板、游戏状态同步等实时应用
• 📣 通知系统：基于频道的事件推送服务
• 📦 微前端桥接：跨子应用的事件总线通信

🧠 最后

如果你正在构建一个对实时性要求较高的 Web 项目，希望 websocket-client-plus 能为你提供一个稳定可靠的长连接方案，减少重复造轮子，专注业务逻辑。

如果你在使用过程中遇到问题，或者对 websocket-client-plus 感兴趣，欢迎一起交流探讨。

📬 可加微信（备注 “WebSocket + 昵称”）：g_adiu