更新记录

1.0.0（2026-03-02） 下载此版本

发布插件

平台兼容性

uni-app x(4.11)

Global WebSocket UTS 插件

一个基于 UTS 的全局 WebSocket 单例模块，适用于：

• IM
• RTC 信令
• 实时消息系统
• 长连接业务

特性

• 全局单例
• 自动 bind
• 自定义心跳格式
• 心跳超时检测
• 指数退避自动重连
• 最大重连次数保护
• 手动 close 不触发重连
• 完整回调支持

目录结构

uni_modules/
  global-wss/
    package.json
    utssdk/
      index.uts

安装方式

将插件放入：

uni_modules/global-wss/

在页面或 App 中引用：

import { globalWss } from "@/uni_modules/global-wss"

初始化

建议在 App.vue 中初始化一次。

globalWss.init(
  "wss://your-server.com",
  () => {
    return JSON.stringify({
      type: "bind",
      token: "your-token"
    })
  },
  () => {
    return JSON.stringify({
      type: "ping",
      time: Date.now()
    })
  },
  30000
)

参数说明

参数 类型 说明

url string WebSocket 地址 buildBind () => string 自定义 bind 消息 buildHeartbeat () => string 自定义心跳消息 heartbeatInterval number 心跳间隔（毫秒）

连接

globalWss.connect()

连接成功后：

• 自动发送 bind
• 自动启动心跳
• 自动重置重连计数

发送消息

globalWss.send(JSON.stringify({
  type: "message",
  content: "hello"
}))

建议通过：

globalWss.isReady()

判断连接状态。

手动关闭

globalWss.close()

行为：

• 清除心跳
• 清除重连定时器
• 关闭 socket
• 不会自动重连

适用场景：

• 用户登出
• 切换账号
• 主动释放连接

自动重连机制

触发条件：

• onClose
• onError
• 心跳超时

策略：

• 指数退避
• 延迟 = 基础间隔 × 当前重连次数
• 最大重连次数默认 10 次

超过最大次数后停止重连。

心跳机制

默认：

• 心跳间隔 30 秒
• 心跳超时 10 秒

流程：

1. 定时发送心跳
2. 启动超时检测
3. 若超时未收到消息
4. 主动断开并触发重连

收到任意消息都会重置超时计时器。

事件监听

globalWss.onOpen(() => {})
globalWss.onClose(() => {})
globalWss.onError(() => {})
globalWss.onMessage((msg) => {})

方法 说明

onOpen 连接成功 onClose 连接关闭 onError 连接异常 onMessage 收到消息

推荐使用方式

长连接业务（IM / RTC）

• 在 App.vue 中 init
• 在登录成功后 connect
• 在登出时 close
• 页面仅监听消息

设计原则

• 单例模式
• 模块内部自维护状态
• 页面无需管理重连
• 手动关闭优先级最高
• 避免并发重连
• 防止死循环重连

版本说明

当前版本特性：

• 单连接
• 自动 bind
• 自动心跳
• 自动重连
• 指数退避
• 手动关闭安全
• 生产可用