简介：面向微信小程序开发者的实时通讯技术资料，基于WebSocket协议讲解聊天对话功能的完整实现方案。内容涵盖连接建立、事件监听、消息收发与界面更新等核心环节，并给出可直接参考的代码示例，重点分析了wx.connectSocket()、SocketTask对象及onMessage消息处理等关键技术点，适合需要在小程序中快速落地聊天功能的中级开发者学习。压缩包内共1个文件，为PDF格式文档，整体大小仅54KB，便于随时查阅与离线阅读。目前已有3256人学习下载，配套讲解结合原理说明与代码拆解，能帮助读者理解WebSocket通讯机制，掌握从连接创建到消息推送的完整链路，同时规避网络异常、断线重连等常见问题，是一份实践性较强的快速入门参考。
1. 微信小程序WebSocket聊天对话功能：先搞定连接，再谈聊天
做小程序客服、群聊或一对一私聊时，最怕的不是发消息慢，而是连接悄悄断掉：页面还在，消息却发不出去；iOS切后台回来，会话已经失效；真机上偶发handshake failed，开发者工具里却一切正常。这些问题的核心都在于：微信小程序里的 WebSocket 不是浏览器的new WebSocket()，它有自己的连接 API、权限校验和生命周期陷阱。聊天对话功能能不能落地，不是看你会不会发一条消息，而是看你能不能把连接、心跳、重连、消息确认这一整套链路理顺。这篇文章我从wx.connectSocket写起，到协议设计、本地消息队列、断线重连，最后收在联调和排错上，所有代码均可在真实项目里直接用。
2. WebSocket连接的生命周期：wx.connectSocket、socketTask与握手排错
2.1 小程序WebSocket API与浏览器WS的区别
浏览器环境里创建 WebSocket 是标准做法：
const ws = new WebSocket('ws://chat.example.com')微信小程序没有这个概念，它把 WebSocket 封装成了wx.connectSocket，并且要求通过socketTask来管理后续事件。第一点区别是 URL 协议：正式环境必须使用wss://，微信后台要配置 socket 合法域名，否则真机直接报url not in domain list。第二点区别是请求头：wx.connectSocket支持header字段，我可以在这里塞 token 或业务参数，而浏览器 WebSocket 的 header 是不可控的。
const socketTask = wx.connectSocket({ url: 'wss://chat.example.com/ws', header: { 'Authorization': 'Bearer ' + wx.getStorageSync('token') }, timeout: 8000, // 握手超时，单位毫秒 success(res) { console.log('connectSocket 调用成功', res) } })这个socketTask就是后面所有事件监听的入口。timeout参数很多人会忽略，默认值在小程序里并不总是符合聊天场景，我一般设成 8000 到 10000 毫秒。如果握手在超时时间内没有完成，会触发onError，但连接任务本身还在，需要手动close清理。注意success只代表 API 调用被接受，不代表 WebSocket 已经打开，真正的连接成功要看socketTask.onOpen。
2.2 从URL到onOpen：一次完整握手的四个状态
WebSocket 连接有一个明确的状态机：CONNECTING、OPEN、CLOSING、CLOSED。小程序里虽然不直接暴露readyState枚举，但socketTask上同样能拿到状态：socketTask.readyState，数字 0 到 3 对应上述四个状态。我在项目里会这样封装状态判断：
function isWsOpen(task) { return !!task && task.readyState === 1 // 1=OPEN }一次完整握手的过程可以拆成四步，下面这张表是我排查问题时的对照依据：
| 阶段 | socketTask事件 | 可能的触发原因 | 排查方向 |
|---|---|---|---|
| CONNECTING | 未触发onOpen，可能触发onError | 域名未配置、服务端不可达、header格式错误 | 看onError里的errMsg |
| OPEN | onOpen | 握手成功，101状态码 | 可以主动send |
| CLOSING | onClose即将触发 | 本地close或服务端关闭帧 | 记录code和reason |
| CLOSED | onClose | 网络断开、服务端异常、超时 | 触发重连策略 |
在这里最容易踩的坑是：在socketTask上注册onOpen之前，连接可能已经完成了握手。wx.connectSocket返回的socketTask在同步状态下就可以挂事件，所以代码顺序应该放在success回调之外、紧随函数调用之后，而不是等success再挂。否则极端情况下会漏掉onOpen事件，导致后续消息永远收不到。
2.3 用socketTask管理多个聊天连接
聊天页面里经常有“客服会话”和“系统通知”两个连接需求。我的建议是：业务上保持一个连接，用消息里的type字段区分频道；如果确实要多个连接，就给每个连接独立维护socketTask，不要用全局变量互相覆盖。
class ChatSocket { constructor(url, token) { this.url = url this.token = token this.task = null } connect() { this.task = wx.connectSocket({ url: this.url, header: { 'Authorization': 'Bearer ' + this.token }, timeout: 10000 }) this.task.onOpen(() => { console.log('连接已打开') this.send({ type: 'auth', data: { token: this.token } }) }) this.task.onMessage((res) => { console.log('收到消息', res.data) }) this.task.onClose((code, reason) => { console.log('连接关闭', code, reason) this.task = null }) this.task.onError((err) => { console.log('连接错误', err.errMsg) }) } }注意onMessage回调里的res.data默认是字符串，如果后端返回二进制帧，需要判断res.data的类型。还有一点：connect()被重复调用时，一定要先关掉旧连接，否则小程序底层会同时维护多个 WebSocket，真机上很容易出现“消息串线”的诡异问题。我在connect()开头加了if (this.task) { this.task.close({ code: 1000 }) }。
2.4 握手失败时的三类报错排查
社区里最集中的报错是handshake failed due to invalid upgrade header: null，这个我放在最后一章专门说。这里先讲另外两类：域名校验失败和握手超时。
域名校验失败的表现是url not in domain list，开发工具里通常在“详情 - 本地设置”勾选“不校验合法域名”，但真机必须到小程序管理后台配置 socket 合法域名。注意：socket 合法域名和 request 合法域名是两套，很多人只配了 request，结果wss://连不上。
握手超时则表现为timeout，先看服务端日志有没有收到 HTTP Upgrade 请求。常见后端框架里 WebSocket 握手依赖于正确的Upgrade头，如果服务端前面有 Nginx，还需要单独处理 WebSocket 升级请求，否则就可能出现上面的 invalid upgrade header。我通常会在服务端写一个最小接口，先让握手成功，再做业务协议。
3. 聊天协议、心跳与本地消息队列：把双向通道做成可靠消息
3.1 一条消息长什么样：type、seq、ack的JSON约定
很多新手会把 WebSocket 当成“可以随时发文本的通道”，直接send('你好')。这样做 demo 没问题，但线上聊天会立刻遇到三个问题：分不清消息是谁发的、消息是否到达、重复消息怎么去重。我习惯把消息定义成 JSON 对象：
{ "type": "chat", "seq": 1024, "ack": 1023, "ts": 1710000000, "payload": { "from": "user_123", "to": "user_456", "content": "你好" } }type区分chat、ping、pong、ack、auth、system；seq是客户端生成的单调递增序号，用于请求确认；ack是服务端回执时携带的“最近收到序号”。为什么要ack？因为 TCP 层只能保证字节送达，不能保证业务逻辑已经入库。聊天场景里，用户最关心的其实是“消息有没有发出”，ack就是业务层的送达回执。
发送时的代码也很简单，但有一个参数容易忽略：
sendMsg(content) { const message = { type: 'chat', seq: this.seq++, ts: Math.floor(Date.now() / 1000), payload: { content } } this.pendingQueue.set(message.seq, message) this.socketTask.send({ data: JSON.stringify(message), success: () => { console.log('已发送到网络层', message.seq) }, fail: (err) => { console.log('发送失败', err.errMsg) } }) }send的success只代表数据交给了小程序底层网络栈，不代表服务端处理成功。所以真正决定消息可靠性的，是pendingQueue里的待确认消息能不能在收到ack后被清除，以及失败时怎么处理。
3.2 心跳逻辑怎么设计：ping间隔、pong超时与半开连接
WebSocket 连接长时间空闲，中间设备可能主动断掉连接，但客户端和服务端都不知道连接已经死了。这种状态叫“半开连接”。微信小程序里最典型的表现是：页面一直开着，第二天再发消息，send没有任何报错，但服务端收不到，就在几秒后触发onClose。解决方法是定时发ping，服务端回pong。
startHeartbeat() { this.heartbeatTimer = setInterval(() => { if (!isWsOpen(this.socketTask)) { console.log('心跳时连接已断开') return } const ping = { type: 'ping', ts: Date.now() } this.socketTask.send({ data: JSON.stringify(ping) }) this.pongTimer = setTimeout(() => { console.log('pong超时，主动close') this.socketTask.close({ code: 4001, reason: 'pong timeout' }) }, 10000) }, 30000) }参数怎么定？30 秒发一次 ping，10 秒内没收到 pong 就判定连接异常。这两个值不是越大越好：间隔太短费电费流量，太长又不能在用户察觉前恢复。我一般建议局域网开发环境用30s/10s，线上生产环境可以宽松到45s/15s。收到任何服务端消息，都应该重置 pong 超时，因为chat、ack都说明连接活着，不必死等pong。
this.socketTask.onMessage((res) => { const msg = JSON.parse(res.data) if (msg.type === 'pong') { clearTimeout(this.pongTimer) this.pongTimer = null } // 其他消息处理 })注意JSON.parse可能抛异常，一定要用try...catch包住，否则一条非法消息会让整个消息循环崩溃。这是我在生产环境踩过的坑。
3.3 本地队列与消息重发：发送失败时到底重不重
聊天消息失败后重发是个双刃剑：不重发，用户眼睁睁看着消息丢失；盲目重发，服务端可能收到两条一模一样的。所以重发的前提是seq去重。我的实现是：pendingQueue里存待确认消息，收到ack后删除，断线重连后统一重发，但最多重试三次。
async resendPending() { if (this.pendingQueue.size === 0) return const entries = Array.from(this.pendingQueue.entries()) for (const [seq, message] of entries) { const retryCount = message.retryCount || 0 if (retryCount >= 3) { console.log('消息超过重试上限', seq) this.pendingQueue.delete(seq) continue } message.retryCount = retryCount + 1 this.pendingQueue.set(seq, message) this.socketTask.send({ data: JSON.stringify(message) }) } }这里有个容易误判的点：重发和发送失败不是一回事。send的fail回调表示网络层写入失败，消息根本没离开手机；而ack没有及时收到，可能是网络链路闪断，也可能是服务端处理慢。我建议对sendfail 的消息立即标记为“发送失败”并在 UI 上显示小红点，对无ack的消息只在重连后重发，不打扰用户。
4. 断线重连与iOS后台限制：线上聊天不掉的四个参数
4.1 指数退避重连：参数表和边界
WebSocket 断线重连最忌讳的是“断线瞬间立刻重连”，多个用户同时断线会打爆服务端。指数退避的意思是把重连间隔按指数增长，并且加入随机抖动。
| 参数 | 推荐值 | 说明 |
|---|---|---|
| 基础延迟 | 1000ms | 第一次重连等待 |
| 最大延迟 | 30000ms | 间隔上限 |
| 倍率 | 2 | 每次失败翻倍 |
| 抖动 | 0.3 | 随机增减30%防止雪崩 |
| 最大重试次数 | 5 | 超过后停止，等用户手动触发 |
代码可以直接贴在连接管理类里：
let retryCount = 0 function scheduleReconnect() { if (retryCount >= 5) { console.log('重连次数太多，等待用户手动重连') return } const base = Math.min(1000 * Math.pow(2, retryCount), 30000) const jitter = 0.3 * base * (Math.random() - 0.5) const delay = Math.floor(base + jitter) console.log(`第 ${retryCount + 1} 次重连，延迟 ${delay}ms`) setTimeout(() => { retryCount++ chatSocket.connect() }, delay) }重连成功后的第一件事，不是发缓存消息，而是先做一次轻量auth。服务端收到新连接的auth后，再决定是否把离线消息推给客户端。这里顺序反了会导致：客户端先发送聊天内容，但因为还没有认证，被服务端直接丢弃。
4.2 iOS小程序WebSocket被挂起之后怎么办
微信小程序在 iOS 上切到后台之后，系统不会立刻杀死小程序，但 WebSocket 会被挂起。具体表现是：聊天页面从后台恢复，readyState仍然是 1（OPEN），但发消息没有任何响应，之后过一会儿才触发onClose。所以不能只看readyState，要在onShow时做一个“活性探测”。
onShow() { if (!isWsOpen(this.socketTask)) { this.connect() return } // 连接看似还在，发一个ping探测 this.socketTask.send({ data: JSON.stringify({ type: 'ping' }), success: () => {}, fail: () => this.closeAndReconnect() }) }这里有个细节：send即使成功，也不能保证数据真的出去了。更可靠的做法是记录上一次收到服务端消息的时间，onShow时如果距离现在超过 60 秒，就主动close重连。
4.3 onHide/onShow与连接状态同步
为了不让重连逻辑散落在每个页面，我把连接状态统一放在app.globalData里，用全局的chatSocket实例。页面onHide时不做任何操作，让心跳自动维持；onShow时调用统一的ensureConnected()方法。
ensureConnected() { if (isWsOpen(this.task)) { console.log('连接正常，跳过重连') return } console.log('连接断开，开始重连流程') retryCount = 0 this.connect() }注意一个常见的坑：onShow里有用户交互，如果立刻同步重连，可能因为网络还没准备好而失败。我通常会在onShow里加一个 300ms 的setTimeout，给底层网络恢复留点时间。同时要标记“正在重连”的复用标志，避免onShow、心跳超时、onClose三个回调同一秒触发三次connect()。三个连接并发建立，服务端会看到同一个用户的多个 session。
5. 验证与排错：Postman先联调、真机抓包、升级头报错
5.1 用Postman WebSocket先跑通后端协议
后端接口没写好之前，前端代码写得再花哨也没法调。我一般会用 Postman 的新建 WebSocket 请求，先把握手和消息协议走通。Postman 里的 WebSocket 请求地址填ws://或wss://，在 “Headers” 标签里加上Authorization。连接成功后，按项目里的 JSON 协议发一条ping，看服务端是否回pong。这一步能快速区分是后端问题还是小程序 API 问题。需要注意：Postman 填入的 URL 要和wx.connectSocket的 URL 保持完全一致，包括路径和 query 参数。
5.2 真机抓包与开发者工具对照
微信开发者工具里的网络面板能看 WebSocket 帧，但真机的情况经常和工具不一致。遇到真机连不上、工具能连上，先把以下三点对照检查：域名证书是否完整、wss://是否可用、服务端是否限制同一 IP 的连接频率。如果需要抓真机流量，可以在小程序后台开启调试模式，或者在服务端打印Sec-WebSocket-Key的握手请求信息。不要只看小程序端的日志，服务端日志能给出更多握手细节。
5.3 常见异常：handshake failed due to invalid upgrade header: null
这个报错几乎都是服务端没有正确完成 WebSocket Upgrade。最常见的原因是 Nginx 没有配置Upgrade头传递，或者后端框架的 WebSocket 路由被某个中间件拦截。我建议先在后端单独开一个/ws路由，不做任何鉴权，确认能连上后再加 header。如果服务端是 Node.js 的ws库，检查是否有server.on('upgrade')被其他逻辑消费；如果是 Nginx，要在location里显式加上：
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";改完配置后，用nginx -t检查语法再 reload。最后不要忘了，小程序端 header 不能直接设置Connection和Upgrade，这两个头由微信底层接管，你强行写在header里反而可能导致握手异常。拿掉自定义Upgrade头，重新编译，这个报错通常就消失了。
本文还有配套的精品资源，点击获取
