更新记录

1.0.4（2026-06-13）

• 修复 Web 端 WebSocket 断开/重连逻辑
• 修复 Web 端 SignalR 握手时序（不再提前标记 connected）
• 修复 Web 端 SSE EventSource 误报错误

平台兼容性

uni-app(3.8.0)

uni-app x(3.8.0)

gs-realtime-message

支持 MQTT、WebSocket、SignalR、SSE 四种协议的 uni-app UTS 实时消息插件。

支持平台

注意：App 端需使用自定义基座或正式打包才能调用原生能力。

公网测试地址（演示页已配置）

SignalR 公网几乎没有长期稳定的免费 Hub，请使用项目内本地服务联调。

启动 SignalR 本地测试服务

cd tools/signalr-test-server
dotnet run

演示页选 signalr，地址填 http://localhost:5099/chat，方法名填 Echo，连接后发送消息应收到回显。

快速开始

import { createConnection } from '@/uni_modules/gs-realtime-message'

// WebSocket 示例
const ws = createConnection({
  protocol: 'websocket',
  url: 'wss://ws.vi-server.org/mirror',
  onOpen(res) {
    console.log('已连接', res)
    ws.send('Hello WebSocket')
  },
  onMessage(res) {
    console.log('收到消息', res.data)
  },
  onError(res) {
    console.error('连接错误', res.errMsg)
  },
  onClose(res) {
    console.log('连接关闭', res.errMsg)
  }
})
ws.connect()

MQTT 示例

const mqtt = createConnection({
  protocol: 'mqtt',
  url: 'ws://test.mosquitto.org:8080/mqtt',
  // 也支持简写：test.mosquitto.org:8080/mqtt
  // TCP 模式：tcp://test.mosquitto.org:1883
  clientId: 'uniapp-client-001',
  topics: ['test/topic'],
  qos: 1,
  onOpen() {
    mqtt.send('Hello MQTT', { topic: 'test/topic', qos: 1 })
  },
  onMessage(res) {
    console.log(`[${res.topic}] ${res.data}`)
  }
})
mqtt.connect()

SignalR 示例

const signalr = createConnection({
  protocol: 'signalr',
  url: 'https://your-server.com/chathub',
  accessToken: 'your-token',
  // 额外查询参数（协商与 WebSocket 连接均会携带）
  params: {
    tenantId: '1001'
  },
  // 自定义请求头（协商请求）
  headers: {
    'X-Custom-Header': 'value'
  },
  onOpen() {
    signalr.invoke('SendMessage', 'user', 'Hello SignalR')
  },
  onMessage(res) {
    console.log(res.data)
  }
})
signalr.connect()

说明：accessToken 会同时设置 Authorization: Bearer 请求头，并在 URL 中追加 access_token 参数（H5 WebSocket 无法自定义 Header，需依赖查询参数鉴权）。

SSE 示例

const sse = createConnection({
  protocol: 'sse',
  url: 'https://your-server.com/events',
  // URL 查询参数（H5 端 EventSource 不支持自定义 Header，推荐用 params 传 token）
  params: {
    token: 'your-token'
  },
  // App 端可额外设置请求头
  headers: {
    Authorization: 'Bearer your-token'
  },
  onMessage(res) {
    console.log('SSE:', res.data)
  }
})
sse.connect()

API 说明

createConnection(options)

创建实时消息连接实例，返回 RealtimeClient 对象。

RealtimeClient 方法

ConnectOptions 参数

disconnect(options?)

断开当前连接。

// 静默断开，不触发 onClose
client.disconnect({ emitClose: false })

// 断开后仍允许自动重连（适用于临时切换页面等场景）
client.disconnect({ disableAutoReconnect: false })

reconnect(options?)

手动重试连接：先释放当前传输层，再重新发起连接。

// 立即重连
client.reconnect()

// 3 秒后重连，并重置重试计数
client.reconnect({ delay: 3000, resetRetryCount: true })

依赖说明

Android

• OkHttp 4.12.0（WebSocket / SSE / SignalR）
• HiveMQ MQTT Client 1.3.3（支持 tcp/ssl/ws/wss）

iOS

• CocoaMQTT 2.1.8（MQTT）
• URLSession WebSocket（WebSocket / SignalR / SSE）

开发文档

• UTS 语法
• UTS API 插件