当前位置：首页 > news >正文

微信小程序即时通讯接入指南：实现基本消息收发

news 2026/6/10 16:38:11

笔者简介

长期关注即时通讯、实时互动与小程序应用场景的技术实现，参与过 IM 能力接入、用户体系打通、消息链路设计及移动端/小程序端工程落地相关工作。在实际项目中，持续关注包括腾讯云 IM、即构 ZEGO ZIM、声网 Agora Signaling 等厂商在即时通讯、消息系统和实时互动能力上的产品实践，重点关注 SDK 接入、消息收发、Token 鉴权、会话管理与业务场景落地。本系列文章将围绕即时通讯 SDK 接入与实时互动消息能力实现，持续输出工程实践与场景分析。

在微信小程序业务中，私信聊天、在线客服、社交互动、交易沟通和在线咨询等场景都离不开稳定的即时通讯能力。用户希望消息能够及时送达，业务侧则需要把用户体系、登录态、消息发送、消息接收和异常处理串起来。如果完全自研 IM 链路，通常需要处理长连接、Token 鉴权、断线重连、消息回调、单聊与群聊模型、消息可靠性以及小程序运行环境限制等问题。

对多数团队来说，先基于成熟 SDK 跑通基础消息收发，再逐步扩展业务能力，是更稳妥的接入路径。本文将以 ZEGO ZIM 小程序 SDK 官方文档为基础，围绕「实现基本消息收发」梳理完整接入流程，重点覆盖 SDK 导入、ZIM 实例创建、事件监听、Token 登录、单聊消息发送与接收、退出登录和实例销毁。

本文介绍如何使用 ZIM SDK 在微信小程序平台快速实现基本的单聊会话消息收发功能。
说明
若开发者需要开发其他平台（如百度、支付宝或字节跳动）的小程序，可参考本文档，唯一区别仅为服务器域名配置，详情请参考前提条件。

1 方案介绍

ZIM SDK 提供了如下接入方案：

在此方案中，您需要通过您自己的业务系统实现以下业务逻辑：

搭建客户端的用户管理逻辑，并下发用户 ID 用于客户端登录。
鉴权 Token，建议由您的业务后台自行实现，保证鉴权数据安全。

2 前提条件

在使用 ZIM SDK 前，请确保：

已在 ZEGO 控制台创建项目，获取到了接入 ZIM SDK 服务所需的 AppID 和 ServerSecret。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台自助开通 ZIM 服务（详情请参考项目管理 - 即时通讯），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。
已获取登录 SDK 所需的 Token，详情请参考使用 Token 鉴权。

3 集成 SDK

3.1 （可选）新建项目

此步骤以如何创建新项目为例，如果是集成到已有项目，可忽略此步。
请参考微信开放文档 - 开始创建一个微信小程序。

3.2 导入 SDK

使用 npm 集成 SDK。

执行 npm i zego-zim-miniprogram 命令安装依赖。说明

npm 下载包支持 typescript 语言(推荐)。
如果在 macOS 或 Linux 系统中执行 npm 命令失败，提示 “permission denied”，请在 npm 命令前加上 sudo 重新执行即可。

导入 SDK。

import {ZIM,ZIMError,ZIMAppConfig,ZIMLoginConfig,ZIMMessage,ZIMMessageSendConfig,ZIMMessageSendNotification,ZIMMessageSentResult,ZIMTextMessage,ZIMTokenRenewedResult,
} from 'zego-zim-miniprogram';

通过 CDN 下载。
在浏览器地址栏输入 https://unpkg.com/zego-zim-miniprogram/index.js 后下载到本地。

// 通过本地文件导入 SDK
import { ZIM } from './zego-zim-miniprogram/index.js';// 通过 script 标签加载 SDK// 下载 CDN 到本地
<script src="./zego-zim-miniprogram/index.js"></script>
// unpkg 作为一个基于 npm 生态的公共 CDN 服务，国内访问可能不稳定
<script src="https://unpkg.com/zego-zim-miniprogram/index.js"></script>

4 实现基本收发消息

以下流程中，我们以客户端 A 和 B 的消息交互为例，实现 1v1 通信功能：

4.1 实现流程

请参考跑通示例源码获取源码。

1. 导入类文件

请参考 3.2 导入 SDK，选择 “方式二：从官网下载 SDK，手动集成”，导入 SDK 文件。

2. 创建 ZIM 实例

首先我们需要在项目中创建 ZIM 实例，一个实例对应的是一个用户，表示一个用户以客户端的身份登录系统。
例如，客户端 A、B 分别调用 create 接口，传入在 2 前提条件中获取到的 AppID，创建了 A、B 的实例：

// 静态同步方法，创建 zim 实例，传入 AppID。
// create 方法仅第一次调用时会创建 ZIM 实例，后续调用会返回 null。
const config: ZIMAppConfig = { appID: 0 };
ZIM.create(config);
// 通过 getInstance 获取单实例，避免热更新导致 create 多次创建返回 null。
const zim = ZIM.getInstance();

3. 监听回调事件

在客户端登录前，开发者可以通过调用 on 接口，自定义 ZIM 中的事件回调，接收到 SDK 异常、消息通知回调等的通知。

// 注册监听“运行时错误信息”的回调
zim.on('error', (zim: ZIM, errorInfo: ZIMError) => {console.log('error', errorInfo.code, errorInfo.message);
});// 注册监听“网络连接状态变更”的回调
zim.on('connectionStateChanged', (zim: ZIM, data: ZIMEventOfConnectionStateChangedResult) => {console.log('connectionStateChanged', data);// 当长时间网络连接断开导致SDK内部登出时，需要重新登录const state = data.state;const event = data.event;if (state == 0 && event != 0 && event != 4 && event != 5) {zim.login(userID, config)}
});// 注册监听“收到单聊消息”的回调
zim.on('peerMessageReceived', (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => {console.log('peerMessageReceived', data);
});// 注册监听“Token 即将过期”的回调
zim.on('tokenWillExpire', (zim: ZIM, data: ZIMEventOfTokenWillExpireResult) => {console.log('tokenWillExpire', data);// 可以在这里调用 renewToken 接口来更新 token// 新 token 生成可以参考上文zim.renewToken(token).then((res: ZIMTokenRenewedResult) => {// 更新成功}).catch((err: ZIMError) => {// 更新失败});
});

详细的接口介绍，请参考 connectionStateChanged、peerMessageReceived、tokenWillExpire。

4. 登录 ZIM

申请 Token
登录 ZIM 需要用于验证身份的 Token，开发者可以直接 ZEGO 控制台获取临时 Token（有效期为 24 小时）来使用，详情请参考控制台 - 开发辅助。
注意
临时 Token 仅供调试，正式上线前，请从开发者的业务服务器生成 Token，详情可参考使用 Token 鉴权。
登录 ZIM
创建实例后，客户端 A 和 B 需要登录 ZIM，只有登录成功后才可以开始发送、接收消息、更新 Token 等。
客户端需要使用各自的用户信息和 Token 进行登录。调用 login 接口进行登录，传入 userID 和 ZIMLoginConfig 对象（必须包含 Token），等待 Token 鉴权通过后才能登录成功。
注意

“userID”、“userName” 支持开发者自定义规则生成。建议开发者将 “userID” 设置为一个有意义的值，可将其与自己的业务账号系统进行关联。
如果 Token 过期，需要在 tokenWillExpire 即将过期回调接口中，调用 renewToken 接口，更新 Token 后才能正常使用 SDK。

// 登录时，需要开发者 按照 "使用 Token 鉴权" 文档生成 token 即可
// userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
// userName 最大 256 字节的字符串，无特殊字符限制。
const userID = 'xxxx';
const config: ZIMLoginConfig = {userName: 'xxxx',token: '',customStatus: '',isOfflineLogin: false,
};zim.login(userID, config).then(() => {// 登录成功}).catch((err: ZIMError) => {// 登录失败});

5. 发送消息

客户端 A 登录成功后，可以向客户端 B 发送消息。
目前 ZIM 支持的消息类型如下：

消息类型	说明
ZIMCommandMessage(2)	开发者可自定义数据内容的信令消息。消息大小不超过 5 KB。
ZIMBarrageMessage(20)	房间内弹幕文本消息。消息大小不超过 5 KB。
ZIMTextMessage(1)	文本消息。消息大小上限默认为 2 KB。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。
ZIMMultipleMessage(10)	组合消息，即包含多个 item 的消息，可包括多条文本、至多 10 张图片、1 个文件、1 个音频、1 个视频和 1 条自定义消息。
ZIMImageMessage(11)	图片消息。支持 JPG、PNG、BMP、TIFF、GIF、WebP，大小不超过 10 MB。
ZIMFileMessage(12)	文件消息。消息内容为文件，格式不限，大小不超过 100 MB。
ZIMAudioMessage(13)	语音消息。支持 MP3、M4A 格式的语音文件，时长不超过 300 秒，大小不超过 6 MB。
ZIMVideoMessage(14)	视频消息。支持 MP4、MOV 格式的视频文件，大小不超过 100 MB。
ZIMCombineMessage(100)	合并消息，消息大小无限制。
ZIMCustomMessage(200)	自定义消息。消息大小上限默认为 2 KB。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。

特性及适用场景

ZIMCommandMessage

限频：单个客户端发送频率限制为 30 次/秒，两次之间间隔 34 毫秒。
不可存储，一般适用于“语聊房”、“在线课堂”等房间内的信令传输，比如上下麦操作、送礼物、发送在线课堂课件等。
支持更高的并发，但不可靠，不保证消息送达和消息顺序。
相关接口：sendMessage

ZIMBarrageMessage

限频：单个客户端发送频率无限制。
不可存储，专门用于房间内的高频、不可靠、允许丢掉的消息，一般适用于发送“弹幕消息”的场景。
支持高并发，但不可靠，不保证消息送达。
相关接口：sendMessage

普通消息类型

适用于：

ZIMTextMessage、ZIMMultipleMessage、ZIMImageMessage、ZIMFileMessage、ZIMAudioMessage、ZIMVideoMessage、ZIMCombineMessage、ZIMCustomMessage

限频：单个客户端发送频率限制为 10 次/秒，两次之间间隔 100 毫秒。
消息可靠有序，可存储为历史消息。
可用于单聊、房间、群聊等即时聊天场景。
房间解散后，“房间聊天”的消息不存储。
图片、文件、语音、视频：通常用于发送富媒体文件类型的消息。
自定义消息：通常用于发送投票类型、接龙类型、视频卡片类型等消息。
组合消息：常用于发送图文消息。
相关接口：sendMessage、replyMessage

以下为发送单聊文本消息为例：客户端 A 可以调用 sendMessage 接口，传入客户端 B 的 userID、消息内容、消息类型 conversationType 等参数，即可发送一条文本消息到 B 的客户端。

ZIMMessageSentResult 回调，判断消息是否发送成功。
onMessageAttached 回调，在消息发送前，可以获得一个临时的 ZIMMessage，以便您添加一些业务处理逻辑。例如：在发送消息前，获取到该条消息的 ID 信息。开发者在发送“视频”等内容较大的消息时，可以在消息上传完成前，缓存该消息对象，直到收到 SDK 发送成功通知时，通过比较对象相同来实现发送前 Loading 的效果。

// 发送单聊 `Text` 信息const toConversationID = ''; // 对方 userID
const conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
const config: ZIMMessageSendConfig = {priority: 1, // 设置消息优先级，取值为 低：1（默认），中：2，高：3
};
const notification: ZIMMessageSendNotification = {onMessageAttached: (message: ZIMMessage) => {// todo: Loading}
}const messageTextObj: ZIMTextMessage = { type: 1, message: 'xxxx' };zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification).then((res: ZIMMessageSentResult) => {// 发送成功}).catch((err: ZIMError) => {// 发送失败});

6. 接收消息

客户端 B 登录 ZIM 后，将会收到在 on 回调中设置的 peerMessageReceived 监听接口，收到客户端 A 发送过来的消息。

// 注册监听“收到单聊消息”的回调
zim.on('peerMessageReceived', (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => {console.log('peerMessageReceived', data);
});

7. 退出登录

如果客户端需要退出登录，直接调用 logout 接口即可。

zim.logout();

8. 销毁 ZIM 实例

如果不需要 ZIM 实例，可直接调用 destroy 接口，销毁实例。
注意
调用 destroy 后会关闭 web socket 长链接，随后 30 秒内，已登录的用户还是处于在线状态；30 秒后，用户才会被 ZIM 后台判断为处于离线状态。如果想立即使当前用户处于离线状态，在调用 destroy 前请先调用 logout。

zim.destroy();

4.2 API 时序图

通过以上的实现流程描述，API 接口调用时序图如下：
说明

发送消息时，统一使用 sendMessage 接口，并根据会话类型传入对应的 conversationType 取值。
接收消息时：
- 单聊消息（Peer 类型），通过 peerMessageReceived 回调接收。
- 房间消息（Room 类型），通过 roomMessageReceived 回调接收。
- 群组消息（Group 类型），通过 groupMessageReceived 回调接收。

结语

本文主要介绍了「实现基本消息收发」的基础接入流程，并结合官方文档梳理了小程序端集成 ZIM SDK、创建实例、监听回调、登录鉴权、发送单聊消息、接收消息以及退出和销毁实例等关键步骤。这一接入路径适用于小程序私信、在线客服、社交聊天、交易沟通、活动互动等典型场景。如果你在接入过程中遇到问题，可以参考下方常见问题或官方文档进一步排查，也可以注册账号后获取一对一技术支持。
在基础消息收发跑通后，开发者还可以继续扩展群聊、房间消息、富媒体消息、离线消息、会话列表、消息历史和好友关系等能力。围绕即时通讯能力，后续还可以继续关注：

ZIM SDK 用户登录与 Token 鉴权实践
单聊、群聊、房间消息的场景差异
文本、图片、文件、语音和视频消息接入
会话列表、历史消息和未读数管理
小程序 IM 异常排查与上线前验证本系列将围绕「即时通讯 SDK 接入与实时互动消息能力实现」持续更新，适合需要构建小程序聊天、在线客服、社交互动和实时消息能力的开发者参考。