Vue中高效使用WebSocket的实战教程‌

Vue 中高效使用 WebSocket 的实战教程

目录

1. 前言

2. WebSocket 基础回顾

   • 2.1 什么是 WebSocket
   • 2.2 与 HTTP 长轮询对比

3. 高效使用的必要性

   • 3.1 常见问题与挑战
   • 3.2 心跳、重连、订阅管理

4. Vue 项目初始化与依赖准备

   • 4.1 创建 Vue 3 + Vite 项目
   • 4.2 安装 Pinia（或 Vuex，可选）

5. WebSocket 服务封装：websocketService.js

   • 5.1 单例模式设计
   • 5.2 连接、断开、重连与心跳
   • 5.3 事件订阅与广播机制

6. Vue 组件实战示例：简易实时聊天室

   • 6.1 目录结构与组件划分
   • 6.2 ChatManager 组件：管理连接与会话
   • 6.3 MessageList 组件：显示消息列表
   • 6.4 MessageInput 组件：输入并发送消息
   • 6.5 数据流动图解

7. 多组件/模块共享同一个 WebSocket 连接

   • 7.1 在 Pinia 中维护状态
   • 7.2 通过 provide/inject 或全局属性共享实例

8. 心跳检测与自动重连实现

   • 8.1 心跳机制原理
   • 8.2 在 websocketService 中集成心跳与重连
   • 8.3 防抖/节流发送心跳

9. 性能优化与最佳实践

   • 9.1 减少重复消息订阅
   • 9.2 批量发送与分包
   • 9.3 合理关闭与清理监听器
10. 常见问题与调试技巧
11. 总结

前言

在现代 Web 应用中，实时通信 已经成为许多场景的核心需求：聊天室、协同协作、股票行情更新、IoT 设备状态监控等。与传统的 HTTP 轮询相比，WebSocket 提供了一个持久化、双向的 TCP 连接，使得客户端和服务器可以随时互相推送消息。对 Vue 开发者而言，如何在项目中高效、稳定地使用 WebSocket，是一门必备技能。

本篇教程将带你从零开始，基于 Vue 3 + Composition API，配合 Pinia（或 Vuex），一步步实现一个“简易实时聊天室”的完整示例，涵盖：

• WebSocket 服务的单例封装
• 心跳检测与自动重连机制
• 多组件/模块共享同一连接
• 批量发送与防抖/节流
• 常见坑与调试技巧

通过代码示例、ASCII 图解与详细说明，让你快速掌握在 Vue 中高效使用 WebSocket 的核心要点。

WebSocket 基础回顾

2.1 什么是 WebSocket

WebSocket 是一种在单个 TCP 连接上进行全双工（bidirectional）、实时通信的协议。其典型握手流程如下：

Client                                   Server
  |    HTTP Upgrade Request              |
  |------------------------------------->|
  |    HTTP 101 Switching Protocols      |
  |<-------------------------------------|
  |                                      |
  |<========== WebSocket 双向数据 ==========>|
  |                                      |

• 客户端发起一个 HTTP 请求，头部包含 Upgrade: websocket，请求将协议升级为 WebSocket。
• 服务器返回 101 Switching Protocols，确认切换。
• 从此，客户端与服务器通过同一个连接可以随时互发消息，无需每次都重新建立 TCP 连接。

2.2 与 HTTP 长轮询对比

高效使用的必要性

3.1 常见问题与挑战

在实际项目中，直接在组件里这样写会遇到很多问题：

// 简易示例：放在组件内
const ws = new WebSocket('wss://example.com/socket');
ws.onopen = () => console.log('已连接');
ws.onmessage = (ev) => console.log('收到消息', ev.data);
ws.onerror = (err) => console.error(err);
ws.onclose = () => console.log('已关闭');

// 在组件卸载时要调用 ws.close()
// 如果有多个组件，需要避免重复创建多个连接

挑战包括：

1. 重复连接：若多个组件各自创建 WebSocket，会造成端口被占用、服务器负载过高，且消息处理分散。
2. 意外断开：网络波动、服务器重启会导致连接断开，需要自动重连。
3. 心跳检测：服务器通常需要客户端周期性发送“心跳”消息以断定客户端是否在线，客户端也要监测服务器响应。
4. 消息订阅管理：某些频道消息只需订阅一次，避免重复订阅导致“重复消息”
5. 资源清理：组件卸载时，需解绑事件、关闭连接，防止内存泄漏和无效消息监听。

3.2 心跳、重连、订阅管理

为了满足以上需求，我们需要将 WebSocket 的逻辑进行集中封装，做到：

• 全局单例：整个应用只维护一个 WebSocket 实例，消息通过发布/订阅或状态管理分发给各组件。
• 心跳机制：定期（如 30 秒）向服务器发送“ping”消息，若一定时间内未收到“pong” 或服务端响应，认为断线并触发重连。
• 自动重连：连接断开后，间隔（如 5 秒）重试，直到成功。
• 订阅管理：对于需要向服务器“订阅频道”的场景，可在封装里记录已订阅频道列表，断线重连后自动恢复订阅。
• 错误处理与退避策略：若短时间内多次重连失败，可采用指数退避，避免服务器或网络被压垮。

Vue 项目初始化与依赖准备

4.1 创建 Vue 3 + Vite 项目

# 1. 初始化项目
npm create vite@latest vue-websocket -- --template vue
cd vue-websocket
npm install

# 2. 安装 Pinia（状态管理，可选）
npm install pinia --save

# 3. 运行开发
npm run dev

项目结构：

vue-websocket/
├─ public/
├─ src/
│  ├─ assets/
│  ├─ components/
│  ├─ services/
│  │   └─ websocketService.js
│  ├─ store/
│  ├─ App.vue
│  └─ main.js
└─ package.json

4.2 安装 Pinia（或 Vuex，可选）

本教程示范用 Pinia 存放“连接状态”、“消息列表”等全局数据，当然也可以用 Vuex。

npm install pinia --save

在 main.js 中引入并挂载：

// src/main.js
import { createApp } from 'vue';
import { createPinia } from 'pinia';
import App from './App.vue';

const app = createApp(App);
const pinia = createPinia();
app.use(pinia);
app.mount('#app');

WebSocket 服务封装：websocketService.js

关键思路：通过一个独立的模块，集中管理 WebSocket 连接、事件订阅、心跳、重连、消息分发等逻辑，供各组件或 Store 调用。

5.1 单例模式设计

// src/services/websocketService.js

import { ref } from 'vue';

/**
 * WebSocket 服务单例
 * - 负责创建连接、断开、重连、心跳
 * - 支持消息订阅/广播
 */
class WebSocketService {
  constructor() {
    // 1. WebSocket 实例
    this.ws = null;

    // 2. 连接状态
    this.status = ref('CLOSED'); // 'CONNECTING' / 'OPEN' / 'CLOSING' / 'CLOSED'

    // 3. 心跳与重连机制
    this.heartBeatTimer = null;
    this.reconnectTimer = null;
    this.reconnectInterval = 5000;    // 重连间隔
    this.heartBeatInterval = 30000;   // 心跳间隔

    // 4. 已订阅频道记录（可选）
    this.subscriptions = new Set();

    // 5. 回调映射：topic => [callback, ...]
    this.listeners = new Map();
  }

  /** 初始化并连接 */
  connect(url) {
    if (this.ws && this.status.value === 'OPEN') return;
    this.status.value = 'CONNECTING';

    this.ws = new WebSocket(url);

    this.ws.onopen = () => {
      console.log('[WebSocket] 已连接');
      this.status.value = 'OPEN';
      this.startHeartBeat();
      this.resubscribeAll(); // 断线重连后恢复订阅
    };

    this.ws.onmessage = (event) => {
      this.handleMessage(event.data);
    };

    this.ws.onerror = (err) => {
      console.error('[WebSocket] 错误：', err);
    };

    this.ws.onclose = (ev) => {
      console.warn('[WebSocket] 已关闭，原因：', ev.reason);
      this.status.value = 'CLOSED';
      this.stopHeartBeat();
      this.tryReconnect(url);
    };
  }

  /** 关闭连接 */
  disconnect() {
    if (this.ws) {
      this.status.value = 'CLOSING';
      this.ws.close();
    }
    this.clearTimers();
    this.status.value = 'CLOSED';
  }

  /** 发送消息（自动包裹 topic 与 payload） */
  send(topic, payload) {
    if (this.status.value !== 'OPEN') {
      console.warn('[WebSocket] 连接未打开，无法发送消息');
      return;
    }
    const message = JSON.stringify({ topic, payload });
    this.ws.send(message);
  }

  /** 订阅指定 topic  */
  subscribe(topic, callback) {
    if (!this.listeners.has(topic)) {
      this.listeners.set(topic, []);
      // 首次订阅时向服务器发送订阅指令
      this.send('SUBSCRIBE', { topic });
      this.subscriptions.add(topic);
    }
    this.listeners.get(topic).push(callback);
  }

  /** 取消订阅 */
  unsubscribe(topic, callback) {
    if (!this.listeners.has(topic)) return;
    const arr = this.listeners.get(topic).filter(cb => cb !== callback);
    if (arr.length > 0) {
      this.listeners.set(topic, arr);
    } else {
      this.listeners.delete(topic);
      // 向服务器发送取消订阅
      this.send('UNSUBSCRIBE', { topic });
      this.subscriptions.delete(topic);
    }
  }

  /** 断线重连后，恢复所有已订阅的 topic */
  resubscribeAll() {
    for (const topic of this.subscriptions) {
      this.send('SUBSCRIBE', { topic });
    }
  }

  /** 处理收到的原始消息 */
  handleMessage(raw) {
    let msg;
    try {
      msg = JSON.parse(raw);
    } catch (e) {
      console.warn('[WebSocket] 无法解析消息：', raw);
      return;
    }
    const { topic, payload } = msg;
    if (topic === 'HEARTBEAT') {
      // 收到心跳响应（pong）
      return;
    }
    // 如果有对应 topic 的监听者，分发回调
    if (this.listeners.has(topic)) {
      for (const cb of this.listeners.get(topic)) {
        cb(payload);
      }
    }
  }

  /** 启动心跳：定时发送 PING */
  startHeartBeat() {
    this.heartBeatTimer && clearInterval(this.heartBeatTimer);
    this.heartBeatTimer = setInterval(() => {
      if (this.status.value === 'OPEN') {
        this.send('PING', { ts: Date.now() });
      }
    }, this.heartBeatInterval);
  }

  /** 停止心跳 */
  stopHeartBeat() {
    this.heartBeatTimer && clearInterval(this.heartBeatTimer);
    this.heartBeatTimer = null;
  }

  /** 自动重连 */
  tryReconnect(url) {
    if (this.reconnectTimer) return;
    this.reconnectTimer = setInterval(() => {
      console.log('[WebSocket] 尝试重连...');
      this.connect(url);
      // 若成功连接后清除定时器
      if (this.status.value === 'OPEN') {
        clearInterval(this.reconnectTimer);
        this.reconnectTimer = null;
      }
    }, this.reconnectInterval);
  }

  /** 清除所有定时器 */
  clearTimers() {
    this.stopHeartBeat();
    this.reconnectTimer && clearInterval(this.reconnectTimer);
    this.reconnectTimer = null;
  }
}

// 导出单例
export default new WebSocketService();

5.2 关键说明

1. status：用 ref 将 WebSocket 状态（CONNECTING/OPEN/CLOSED 等）暴露给 Vue 组件，可用于界面显示或禁用按钮。
2. listeners：维护一个 Map，将不同的 topic（频道）映射到回调数组，方便多处订阅、取消订阅。

3. 心跳机制：定时发送 { topic: 'PING', payload: { ts } }，服务器应在收到后回显 { topic: 'HEARTBEAT' }，单纯返回。例如：

   // 服务器伪代码
   ws.on('message', (msg) => {
     const { topic, payload } = JSON.parse(msg);
     if (topic === 'PING') {
       ws.send(JSON.stringify({ topic: 'HEARTBEAT' }));
     }
     // 其它逻辑…
   });

4. 重连策略：当 onclose 触发时，开启定时器周期重连；如果连接成功，清除重连定时器。简单而有效。
5. 恢复订阅：在重连后重发所有 SUBSCRIBE 指令，确保服务器推送相关消息。

Vue 组件实战示例：简易实时聊天室

下面我们基于上述 websocketService，搭建一个“简易实时聊天室”示例，展示如何在多个组件间高效分发消息。

6.1 目录结构与组件划分

src/
├─ components/
│  ├─ ChatManager.vue    # 负责打开/关闭 WebSocket、登录与管理会话
│  ├─ MessageList.vue    # 实时显示收到的聊天消息
│  └─ MessageInput.vue   # 输入并发送聊天消息
├─ services/
│  └─ websocketService.js
└─ store/
   └─ chatStore.js       # Pinia

6.2 ChatManager 组件：管理连接与会话

负责：登录（获取用户名）、连接/断开 WebSocket、订阅“chat”频道，将收到的消息写入全局 Store。

<template>
  <div class="chat-manager">
    <div v-if="!loggedIn" class="login">
      <input v-model="username" placeholder="输入用户名" />
      <button @click="login">登录并连接</button>
    </div>
    <div v-else class="controls">
      <span>当前用户：{{ username }}</span>
      <span class="status">状态：{{ status }}</span>
      <button @click="logout">退出并断开</button>
    </div>
  </div>
</template>

<script setup>
import { ref, computed, onBeforeUnmount } from 'vue';
import { useChatStore } from '@/store/chatStore';
import websocketService from '@/services/websocketService';

// Pinia Store 管理全局消息列表与用户状态
const chatStore = useChatStore();

// 本地状态：是否已登录
const loggedIn = ref(false);
const username = ref('');

// 连接状态映射显示
const status = computed(() => websocketService.status.value);

// 登录函数：连接 WebSocket 并订阅聊天频道
async function login() {
  if (!username.value.trim()) return alert('请输入用户名');
  chatStore.setUser(username.value.trim());

  try {
    // 1. 连接 WebSocket
    await websocketService.connect('wss://example.com/chat');
    // 2. 订阅 “chat” 频道
    websocketService.subscribe('chat', (payload) => {
      chatStore.addMessage(payload);
    });
    // 3. 向服务器发送“用户加入”系统消息
    websocketService.send('chat', { user: username.value, text: `${username.value} 加入了聊天室` });

    loggedIn.value = true;
  } catch (err) {
    console.error('连接失败：', err);
    alert('连接失败，请重试');
  }
}

// 注销并断开
async function logout() {
  // 发送退出消息
  websocketService.send('chat', { user: username.value, text: `${username.value} 离开了聊天室` });
  // 取消订阅并断开
  websocketService.unsubscribe('chat', chatStore.addMessage);
  await websocketService.disconnect();
  chatStore.clearMessages();
  loggedIn.value = false;
  username.value = '';
}

onBeforeUnmount(() => {
  if (loggedIn.value) {
    logout();
  }
});
</script>

<style scoped>
.chat-manager {
  margin-bottom: 16px;
}
.login input {
  padding: 6px;
  margin-right: 8px;
}
.status {
  margin: 0 12px;
  font-weight: bold;
}
button {
  padding: 6px 12px;
  background: #409eff;
  border: none;
  border-radius: 4px;
  color: white;
  cursor: pointer;
}
button:hover {
  background: #66b1ff;
}
</style>

6.2.1 关键说明

1. 登录后：调用 websocketService.connect('wss://example.com/chat')，然后 subscribe('chat', callback) 订阅“chat”频道。
2. 收到服务器广播的聊天消息时，callback 会把消息推入 Pinia Store。
3. status 计算属性实时反映 websocketService.status 状态（CONNECTING/OPEN/CLOSED）。
4. logout() 先发送离开消息，再 unsubscribe() 并 disconnect()。在组件卸载前调用 logout()，保证资源释放。

6.3 MessageList 组件：显示消息列表

<template>
  <div class="message-list">
    <div v-for="(msg, idx) in messages" :key="idx" class="message-item">
      <span class="user">{{ msg.user }}：</span>
      <span class="text">{{ msg.text }}</span>
      <span class="time">{{ msg.time }}</span>
    </div>
  </div>
</template>

<script setup>
import { computed, nextTick, ref } from 'vue';
import { useChatStore } from '@/store/chatStore';

const chatStore = useChatStore();
const messages = computed(() => chatStore.messages);

const listRef = ref(null);

// 自动滚到底部
watch(messages, async () => {
  await nextTick();
  const el = listRef.value;
  if (el) el.scrollTop = el.scrollHeight;
});

</script>

<style scoped>
.message-list {
  border: 1px solid #ccc;
  height: 300px;
  overflow-y: auto;
  padding: 8px;
  background: #fafafa;
}
.message-item {
  margin-bottom: 6px;
}
.user {
  font-weight: bold;
  margin-right: 4px;
}
.time {
  color: #999;
  font-size: 12px;
  margin-left: 8px;
}
</style>

6.3.1 关键说明

• 从 Pinia Store 中读取 messages 数组，并通过 v-for 渲染。
• 使用 watch 监听 messages 变化，在新消息到来后自动滚动到底部。

6.4 MessageInput 组件：输入并发送消息

<template>
  <div class="message-input">
    <input
      v-model="text"
      placeholder="输入消息后按回车"
      @keydown.enter.prevent="send"
    />
    <button @click="send">发送</button>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { useChatStore } from '@/store/chatStore';
import websocketService from '@/services/websocketService';

const chatStore = useChatStore();
const text = ref('');

// 发送聊天消息
function send() {
  const content = text.value.trim();
  if (!content) return;
  const msg = {
    user: chatStore.user,
    text: content,
    time: new Date().toLocaleTimeString()
  };
  // 1. 先本地回显
  chatStore.addMessage(msg);
  // 2. 发送给服务器
  websocketService.send('chat', msg);
  text.value = '';
}
</script>

<style scoped>
.message-input {
  display: flex;
  margin-top: 8px;
}
.message-input input {
  flex: 1;
  padding: 6px;
  font-size: 14px;
  margin-right: 8px;
  border: 1px solid #ccc;
  border-radius: 4px;
}
.message-input button {
  padding: 6px 12px;
  background: #67c23a;
  border: none;
  color: white;
  border-radius: 4px;
  cursor: pointer;
}
button:hover {
  background: #85ce61;
}
</style>

6.4.1 关键说明

1. 用户输入后，send() 会先将消息推入本地 chatStore.addMessage(msg)，保证“即时回显”；
2. 再执行 websocketService.send('chat', msg)，将消息广播给服务器；
3. 服务器收到后再广播给所有在线客户端（包括发送者自己），其他客户端即触发 handleMessage 并更新 Store。

6.5 数据流动图解

┌─────────────────────────────┐
│        ChatManager.vue      │
│  ┌───────────────────────┐  │
│  │ 点击“登录”：login()   │  │
│  │   ↓                   │  │
│  │ websocketService.connect │  │
│  │   ↓                   │  │
│  │ ws.onopen → startHeartBeat() │
│  │   ↓                   │  │
│  │ subscribe('chat', callback)  │
│  └───────────────────────┘  │
│                              │
│                              │
│  服务器推送 → ws.onmessage    │
│      ↓                         │
│ ChatManager.handleMessage     │
│      ↓                         │
│ chatStore.addMessage(payload) │
└─────────────────────────────┘
           ↑
           │
┌─────────────────────────────┐
│      MessageList.vue         │
│   watch(messages) → 渲染列表  │
└─────────────────────────────┘

┌─────────────────────────────┐
│     MessageInput.vue        │
│ 用户输入 → send()            │
│   ↓                          │
│ chatStore.addMessage(local) │
│   ↓                          │
│ websocketService.send(...)   │
└─────────────────────────────┘

1. 登录：ChatManager.vue 调用 websocketService.connect()，再 subscribe('chat', cb)。
2. 接收消息：ws.onmessage → handleMessage → chatStore.addMessage → MessageList.vue 渲染。
3. 发送消息：MessageInput.vue 先 chatStore.addMessage 提前回显 → 然后 websocketService.send('chat', msg) 发给服务器 → 服务器再广播给所有客户端。（发送者自己也会再次收到并重复渲染，注意过滤或去重）

多组件/模块共享同一个 WebSocket 连接

在大型项目里，往往有多个功能模块都需要通过 WebSocket 通信。我们要保证全局只有一个 WebSocket 实例，避免重复连接。

7.1 在 Pinia 中维护状态

可以将 websocketService 作为单独模块，也可以在 Pinia Store 中维护 WebSocket 实例引用并封装调用。

// src/store/chatStore.js
import { defineStore } from 'pinia';
import websocketService from '@/services/websocketService';

export const useChatStore = defineStore('chat', {
  state: () => ({
    user: '',
    messages: []
  }),
  actions: {
    setUser(name) {
      this.user = name;
    },
    addMessage(msg) {
      this.messages.push(msg);
    }
  },
  getters: {
    messageCount: (state) => state.messages.length
  }
});

注意：websocketService 本身是个独立单例，只要在组件或 Store 里 import 一次，无论何处调用，都是同一个实例。

7.2 通过 provide/inject 或全局属性共享实例

除了 Store，也可以在 App.vue 用 provide('ws', websocketService)，让子组件通过 inject('ws') 直接访问该实例。上述示例在 ChatManager.vue 和 MessageInput.vue、MessageList.vue 中直接 import websocketService 即可，因为它是单例。

心跳检测与自动重连实现

为了保证连接的持久性与可靠性，需要在 websocketService 中内置心跳与重连逻辑。

8.1 心跳机制原理

• 发送心跳：客户端定期（如 30 秒）向服务器发送 { topic: 'PING' }，服务器需监听并回应 { topic: 'HEARTBEAT' }。
• 超时检测：如果在两倍心跳间隔时长内没有收到服务器的 HEARTBEAT，则判定连接已断，主动触发 disconnect() 并启动重连。

// 在 websocketService.handleMessage 中
handleMessage(raw) {
  const msg = JSON.parse(raw);
  const { topic, payload } = msg;
  if (topic === 'HEARTBEAT') {
    this.lastPong = Date.now();
    return;
  }
  // 其余逻辑…
}

// 心跳定时器
startHeartBeat() {
  this.stopHeartBeat();
  this.lastPong = Date.now();
  this.heartBeatTimer = setInterval(() => {
    if (Date.now() - this.lastPong > this.heartBeatInterval * 2) {
      // 认为已断开
      console.warn('[WebSocket] 心跳超时，尝试重连');
      this.disconnect();
      this.tryReconnect(this.url);
      return;
    }
    this.send('PING', { ts: Date.now() });
  }, this.heartBeatInterval);
}

8.2 在 websocketService 中集成心跳与重连

// 修改 connect 方法，保存 url
connect(url) {
  this.url = url;
  // …其余不变
}

tryReconnect(url) {
  // 断开时自动重连
  this.clearTimers();
  this.reconnectTimer = setInterval(() => {
    console.log('[WebSocket] 重连尝试...');
    this.connect(url);
  }, this.reconnectInterval);
}

8.2.1 防抖/节流发送心跳

如果业务场景复杂，可能有大量频繁消息进出，心跳不应与常规消息冲突。可通过节流控制心跳发送：

import { throttle } from 'lodash';

startHeartBeat() {
  this.stopHeartBeat();
  this.lastPong = Date.now();
  const sendPing = throttle(() => {
    this.send('PING', { ts: Date.now() });
  }, this.heartBeatInterval);
  this.heartBeatTimer = setInterval(() => {
    if (Date.now() - this.lastPong > this.heartBeatInterval * 2) {
      this.disconnect();
      this.tryReconnect(this.url);
      return;
    }
    sendPing();
  }, this.heartBeatInterval);
}

性能优化与最佳实践

9.1 减少重复消息订阅

• 某些需求下，不同模块需要监听同一个 topic，直接在 websocketService 的 listeners 将多个回调并存即可。
• 若尝试重复 subscribe('chat', cb)，封装里会判断 this.listeners 是否已有该 topic，若已有则不重新 send('SUBSCRIBE')。

9.2 批量发送与分包

• 当要发送大量数据（如一次性发很多消息），应考虑批量分包，避免一次性写入阻塞。可以用 setTimeout 或 requestIdleCallback 分段写入。
• 亦可将多条消息合并成一个对象 { topic:'BATCH', payload: [msg1, msg2, …] }，在服务器端解包后再分发。

9.3 合理关闭与清理监听器

• 在组件卸载或离开页面时，务必调用 unsubscribe(topic, callback) 或 disconnect()，避免无效回调积累，导致内存泄漏。
• 对于短期连接需求（例如只在某些页面使用），可在路由守卫 beforeRouteLeave 中断开连接。

常见问题与调试技巧

1. 浏览器报 SecurityError 或 ReferenceError: navigator.serial is undefined

   • 确保在 HTTPS 或本地 localhost 环境下运行；
   • 在不支持 Web Serial API 的浏览器（如 Firefox、Safari）会找不到 navigator.serial，需做兼容性提示。

2. WebSocket 握手失败或频繁重连

   • 检查服务端地址是否正确，是否开启了 SSL（如果用 wss://）；
   • 服务器是否允许跨域，WebSocket endpoint 是否配置了 Access-Control-Allow-Origin: *；
   • 在 DevTools Network → WS 面板检查握手 HTTP 请求/响应。

3. 心跳无效无法保持连接

   • 确保服务器代码正确响应 PING，返回 { topic: 'HEARTBEAT' }；
   • 客户端记得在 handleMessage 内及时更新 lastPong 时间戳。

4. 重复消息

   • 如果在重连后没有调用 unsubscribe 就重新 subscribe，可能会收到多份同一消息；
   • 解决：在 connect() 之前先清空 listeners 或使用 Set 去重回调。

5. 消息 JSON 解析失败

   • 确保客户端与服务端约定好消息格式，都是 { topic, payload } 串行化的 JSON；
   • 在 handleMessage 中用 try…catch 捕获解析错误并打印原始 raw 数据。

总结

本文从WebSocket 原理讲起，重点演示了在 Vue 3 + Pinia 项目中，如何通过单例服务 + 心跳/重连 + 订阅管理机制，实现一个高效、稳定、易维护的 WebSocket 通信层。我们完整演示了一个“简易实时聊天室”示例，包括：

• websocketService.js：集中管理连接、断开、重连、心跳、消息订阅/广播。
• ChatManager.vue：负责登录/登出、订阅频道、更新全局 Store。
• MessageList.vue：实时渲染收到的聊天消息，自动滚到底部。
• MessageInput.vue：发送聊天消息并本地回显。

同时讨论了心跳检测与自动重连的实现思路，演示了性能优化（节流、批量分包）和常见问题的排查方法。通过本文内容，你应该能够在自己的 Vue 应用里灵活、高效地集成 WebSocket，实现各种实时通信场景，如：聊天室、实时监控、股价行情、游戏对战等。