更新记录

1.0.0（2025-12-28） 下载此版本

完整版的源码以及说明文档

平台兼容性

uni-app(3.7.2)

createPageWebSocket 使用说明

createPageWebSocket 是一个 uni-app 页面级 WebSocket 管理模块，用于在单个页面中创建并维护一个独立的 WebSocket（wss）连接实例。

该模块以“页面隔离”为核心设计理念，不使用全局单例，也不依赖 Vuex / Pinia，可在任意页面独立引用。

一、设计目标

• 页面级 WebSocket 实例（非全局单例）
• 仅使用 JavaScript，无需原生能力
• 支持自动重连
• 支持心跳保活（完全可配置）
• 支持 uid / token 等绑定协议（完全可配置）
• 生命周期清晰，易于维护

二、重要使用限制（必须阅读）

❗ 一个页面只能使用一个 WebSocket 实例

一个页面内只能创建一个 createPageWebSocket 实例

原因说明：

• uni-app 在 App / 小程序端底层只维护 单一 WebSocket 通道
• 多实例会互相覆盖 onMessage / onOpen / onClose 监听
• 会导致消息丢失、回调错乱等不可预期问题

✅ 推荐做法：

• 一个页面：一个 WebSocket
• 多业务逻辑：通过 type / action / channel 等字段在同一连接中区分

三、模块导出方式

模块采用 default export 方式导出。

export default function createPageWebSocket(options) {
  ...
}

正确引入方式（本模块只使用了js，如果嫌弃路径太长的可以随意移动index.js，移动后根据自己的路径引入即可）

import createPageWebSocket from '@/uni_modules/ranmo-wssmanage/components/ranmo-wssmanage'

四、基础使用示例

export default {
  data() {
        return {
            ws:null,
        }
    },
  onLoad() {
    this.ws = createPageWebSocket({
      url: 'wss://example.com/ws',
      heartbeat: {
        interval: 20000,
        message: () => ({
          action: 'heartbeat',
          time: Date.now()
        })
      },
      bind: {
        message: uid => ({ type: 'bind', uid }),
        isSuccess: data => data?.type === 'bind_success'
      }
      callbacks: {
        connected: () => {
          console.log('WebSocket connected')
        },
        message: msg => {
          console.log('recv message', msg)
        },
        disconnected: () => {
          console.log('WebSocket closed')
        }
      }
    })
    this.ws.connect()
    this.ws.bindUid('user_10001')
  },
  onUnload() {
    this.ws.close()
  },
  methods: {
    sendMessage(){
      this.ws.send({
        type: 'chat',
        content: 'hello'
      })
    }
  }
}

五、配置项说明（options）

1️⃣ url（必填）

WebSocket 服务端地址。

url: 'wss://example.com/ws'

2️⃣ callbacks（可选）

WebSocket 生命周期回调集合。

callbacks: {
  connected,     // 连接成功
  binded,        // uid 绑定成功
  message,       // 收到业务消息
  disconnected,  // 连接断开
  error          // 发生错误
}

示例

callbacks: {
  connected: () => console.log('connected'),
  binded: data => console.log('bind success', data),
  message: msg => console.log('message', msg),
  disconnected: () => console.log('disconnected'),
  error: err => console.error(err)
}

3️⃣ heartbeat（可选）

自定义心跳配置，用于保持连接存活。

配置结构

heartbeat: {
  interval: 30000,
  message: () => ({ type: 'ping' })
}

字段说明

示例：自定义心跳协议

heartbeat: {
  interval: 20000,
  message: () => ({
    action: 'heartbeat',
    time: Date.now()
  })
}

说明：

• message 必须是函数
• 返回 null / false 时，将跳过本次心跳发送

4️⃣ bind（可选）

自定义 uid / token 绑定协议。

配置结构

bind: {
  message: uid => ({ type: 'bind', uid }),
  isSuccess: data => data?.type === 'bind_success'
}

字段说明

示例：自定义绑定协议

bind: {
  message: uid => ({
    action: 'bindUser',
    user_id: uid
  }),
  isSuccess: data => data?.code === 0
}

触发绑定

this.ws.bindUid('user_10001')

六、实例方法说明

const ws = createPageWebSocket(options)

ws.connect()

建立 WebSocket 连接。

• 建议在 onLoad 中调用
• 重复调用会被内部忽略

ws.send(data)

发送业务消息。

ws.send({
  type: 'chat',
  content: 'hello'
})

ws.bindUid(uid)

发送绑定消息。

• 如果在未连接状态调用
• 会在连接成功后自动执行

ws.bindUid('user_10001')

ws.close()

主动关闭连接，并停止自动重连。

• 建议在 onUnload 中调用

ws.close()

七、自动重连机制说明

• 非手动关闭（如断网、服务端断开）会触发自动重连
• 重连成功后：
  • 自动恢复心跳
  • 如果已绑定 uid，会自动重新绑定

八、设计原则

• 不依赖全局变量
• 不侵入页面逻辑
• 不限制后端协议
• 心跳 / bind 规则完全由业务决定
• 页面卸载即释放所有资源

九、适用后端

• GatewayWorker
• Swoole WebSocket
• Node.js ws
• Java / Go WebSocket
• 任意标准 WebSocket 服务

十、总结

createPageWebSocket 是一个：

轻量、可配置、页面隔离、工程化友好的 uni-app WebSocket 解决方案