如今大部分 App、小程序都离不开即时聊天功能。如果纯手写通讯逻辑，开发量大、耗时久，还容易出现各种兼容问题。

借助ZIM SDK，能快速搞定聊天、消息收发、会话管理等核心能力，开发效率大幅提升。本文就用uni-app + ZIM SDK，手把手带大家快速搭建一套可直接使用的即时通讯聊天功能。

一、典型应用场景

  • 1V1 单聊：好友私聊、客服对话、陌生人实时沟通

  • 群聊聊天：兴趣群、工作群、班级群，支持多人实时消息互动

  • 在线客服：APP 内置客服，用户与客服快速文字沟通

  • 社交互动：搭配音视频房间，实现文字 + 语音 / 视频联动聊天

二、集成 IM 即时通讯SDK 的前提条件

在使用 ZIM SDK 前，请确保：

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

  • 已获取登录 SDK 所需的 Token，详情请参考 使用 Token 鉴权。

三、集成uniapp IM 即时通讯 SDK

1 .（可选）新建项目

此步骤以如何创建新项目为例，如果是集成到已有项目，可忽略此步。

1.1 启动 HBuilderX，选择“文件 > 新建 > 项目”菜单。

1.2 在出现的表单中，选择 “uni-app” 平台，并填写项目名称，并点击创建即可

2.导入 SDK

2.1 以下两种方式可以任选一种下载 SDK

方式一：从 ZEGO 官网下载

  1. 请参考 下载 页面，获取最新版本的 SDK 到本地，并将得到的 “zego-ZIMUniPlugin.zip” 文件解压缩。

  2. 将解压缩后的文件夹，直接复制到项目工程根目录下的 “nativeplugins” 文件夹，如果没有该目录，请手动创建。

方式二：从插件市场获取 从 uni-app 插件市场获取 ZIM SDK 原生插件

通过 uni-app 插件市场也有两种方式导入，请任选一种：

  • 单击 “购买（0元） for 云打包”，选择相应的项目导入。

  • 单击 “下载 for 离线打包”，离线导入。

    • 下载 SDK 到本地，并将得到的 “zego-ZIMUniPlugin.zip” 文件解压缩。

    • 将解压缩后的文件夹，直接复制到项目工程根目录下的 “nativeplugins” 文件夹，如果没有该目录，请手动创建。

2.2在 uni-app 项目中导入原生插件

1.单击项目目录的 “manifest.json” 文件后，单击 “App原生插件配置” 中的 “选择本地插件” 或 “选择云端插件”。

2.在弹出的选择框中，选择 “Zego ZIM 即时通讯 SDK” 后，单击“确认”，即添加成功。

2.3.在 uni-app 项目中导入 JS 封装层插件

以下两种方式可以任选一种导入。

  • 方式一：请参考 下载 页面，获取最新版本的 JS 封装层到本地，并将得到的 “zego-ZIMUniplugin-JS.zip” 文件解压缩。

  • 下载的 JS 封装层可以拷贝到 HBuilderX 的 “js_sdk” 目录中。（如无该目录，请创建一个）

  • 导入的 JS 封装层将存储在 “js_sdk” 目录中。

2.4 在 uni-app 项目中使用原生插件

import ZIM from '../js_sdk/zego-ZIMUniplugin-JS/lib/index.js';

3.开发 iOS/Android 应用（自定义调试基座）

3.1 制作自定义调试基座

  1. 选择 “运行 > 运行到手机或模拟器 > 制作自定义调试基座” 菜单。

   2.在弹出的界面中，按照 uni-app 教程|blank，填写相关信息，并单击“打包”进行云打包。

3.打包成功后，控制台会收到 uni-app 的相关提示。

3.2 切换运行基座为自定义调试基座

自定义调试基座，请选择“运行 > 运行到手机或模拟器 > 运行到 Android App 基座 > 使用自定义基座运行”菜单。

4. 开发 鸿蒙 应用

请选择“运行 > 运行到手机或模拟器 > 运行到鸿蒙。

5 .开发 Web/小程序 应用

uni-app 项目开发 Web 和 小程序平台时，需要通过手动下载对应平台的 SDK 来集成。

  • 下载对应的 SDK：Web SDK、小程序 SDK。

  • 在项目 js_sdk 目录下新建 zego-zim-web 目录和 zego-zim-miniprogram 目录，并分别将下载的 index.js 文件复制到对应目录下。

  • 在项目中导入 SDK。

// Web 和 小程序：通过对应平台 JS 文件集成

// #ifdef H5
import { ZIM } from '../js_sdk/zego-zim-web/index.js';
// #endif

// #ifdef MP
import { ZIM } from '../js_sdk/zego-zim-miniprogram/index.js';
// #endif

6.实现基本收发消息

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

6.1 实现流程

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

1.导入 SDK 文件

导入 SDK 文件。

2.创建 ZIM 实例

首先我们需要在项目中创建 ZIM 实例，一个实例对应的是一个用户，表示一个用户以客户端的身份登录系统。

例如，客户端 A、B 分别调用 create 接口，传入在前提条件中获取到的 AppID，创建了 A、B 的实例：

import {
    ZIM,
    ZIMError,
    ZIMAppConfig,
    ZIMLoginConfig,
    ZIMMessage,
    ZIMMessageSendConfig,
    ZIMMessageSendNotification,
    ZIMMessageSentResult,
    ZIMTokenRenewedResult,
} from '@/uni_modules/zego-zim-uts';

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

在客户端登录前，开发者需要注册 ZIM 中的事件回调，接收到 SDK 异常、收到消息等通知。

// 注册监听“运行时错误信息”的回调  
zim.onError((errorInfo) => {
    console.log('error', errorInfo.code, errorInfo.message);
});

// 注册监听“网络连接状态变更”的回调
zim.onConnectionStateChanged((data) => {
    console.log('connectionStateChanged', data);
});

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

// 注册监听“Token 即将过期”的回调
zim.onTokenWillExpire((data) => {
    console.log('tokenWillExpire', data);
    // 可以在这里调用 renewToken 接口来更新 token
    // 新 token 生成可以参考上文
    zim.renewToken(token)
        .then((res: ZIMTokenRenewedResult) => {
            // 更新成功
        })
        .catch((err) => {
            // 更新失败
        })
});

详细的接口介绍，请参考 onConnectionStateChanged、onPeerMessageReceived、onTokenWillExpire。

6.2登录 ZIM

创建实例后，客户端 A 和 B 需要登录 ZIM，只有登录成功后才可以开始发送、接收消息等。

客户端需要使用各自的用户信息进行登录。调用 login 接口进行登录，传入 userID 和 ZIMLoginConfig 对象，进行登录。

注意

  • “userID”、“userName” 支持开发者自定义规则生成。建议开发者将 “userID” 设置为一个有意义的值，可将其与自己的业务账号系统进行关联。

  • 默认鉴权方式为 “AppSign 鉴权”，登录 ZIM 时Token 传入空字符串即可。

  • 如果您使用的是 “Token 鉴权”，请参考 使用 Token 鉴权 文档，获取 Token 后，并在登录 ZIM 时传入 Token，鉴权通过后才能登录成功。

// userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
// userName 最大 256 字节的字符串，无特殊字符限制。
const userID = 'xxxx';
const config: ZIMLoginConfig = {
    userName: 'xxxx',
    token: '',
    customStatus: '',
    isOfflineLogin: false,
};

// 登录时：
// 使用 Token 鉴权，需要开发者填入 "使用 Token 鉴权" 文档生成的 Token，详情请参考 [使用 Token 鉴权]
// 使用 AppSign 鉴权 (2.3.0 或以上版本的默认鉴权方式)，Token 参数填空字符串

zim.login(userID, config)
    .then(() => {
        // 登录成功
    })
    .catch((err) => {
        // 登录失败
    });

6.3发送消息

客户端 A 登录成功后，可以向客户端 B 发送消息。

目前 ZIM 支持的消息类型如下：

消息类型 说明 特性及适用场景
ZIMCommandMessage(2) 开发者可自定义数据内容的信令消息。消息大小不超过 5 KB。 限频：单个客户端发送频率限制为 30 次/秒（两次之间间隔 34 毫秒）。不可存储，一般适用于“语聊房”、“在线课堂”等房间内的信令传输，比如上下麦操作、送礼物，发送在线课堂课件等。支持更高的并发，但不可靠，不保证消息送达和消息顺序。相关接口：sendMessage
ZIMBarrageMessage(20) 房间内弹幕文本消息。消息大小不超过 5 KB。 限频：单个客户端发送频率无限制。不可存储，专门用于房间内的高频、不可靠、允许丢掉的消息，一般适用于发送“弹幕消息”的场景中。支持高并发，但不可靠，不保证消息送达。相关接口：sendMessage
ZIMTextMessage(1) 文本消息。消息大小上限默认为 2 KB。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。 限频：单个客户端发送频率限制为 10 次/秒（两次之间间隔 100 毫秒）。消息可靠有序，可存储为历史消息（保存时间请参考 计费说明 - 版本差异 中“历史消息存储天数”）。
可用于单聊、房间、群聊等即时聊天场景。房间解散后，“房间聊天”的消息不存储。图片、文件、语音、视频：通常用于发送富媒体文件类型的消息。自定义消息：通常用于发送投票类型、接龙类型、视频卡片类型等消息。组合消息：常用于发送图文消息。相关接口：sendMessage、replyMessage
ZIMMultipleMessage(10) 组合消息，即包含多个 item 的消息，可包括多条文本、至多 10 张图片、1 个文件、1 个音频、1 个视频和 1 条自定义消息。说明Item 总量不得超过 20。图片 + 视频的数量最多不能超过 10。图片、音频、文件和视频的大小和格式限制与对应的富媒体消息类型相同。
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。说明若要在消息发送成功后获取视频首帧的宽高信息，视频必须使用 H.264 或 H.265 编码格式。
ZIMCombineMessage(100) 合并消息，消息大小无限制。
ZIMCustomMessage(200) 自定义消息。消息大小上限默认为 2 KB。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。开发者可自定义消息的类型，并自行完成消息的解析，ZIM SDK 不负责定义和解析自定义消息的具体内容。

以下为发送单聊文本消息为例：客户端 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: ZIMMessage = { type: 1, message: 'xxxx' };

zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 发送成功
    })
    .catch((err) => {
        // 发送失败
    });

6.4接收消息

客户端 B 登录 ZIM 后，通过 onPeerMessageReceived 监听接口，收到客户端 A 发送过来的消息。

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

6.5退出登录

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

zim.logout();

6.6销毁 ZIM 实例

如果不需要 ZIM 实例，可直接调用 destroy 接口，销毁实例。

zim.destroy();1

7. API 时序图

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

说明

  • 发送消息时，统一使用 sendMessage 接口，并根据会话类型传入对应的 conversationType 取值。

  • 接收消息时：

    • 单聊消息（Peer 类型），通过 onPeerMessageReceived 回调接收。

    • 房间消息（Room 类型），通过 onRoomMessageReceived 回调接收。

    • 群组消息（Group 类型），通过 onGroupMessageReceived 回调接收。

四、常见问题与解决方案

1.插件导入后不生效

  • 必须使用自定义调试基座

  • 检查 nativeplugins 目录结构是否正确

  • 确认 manifest.json 已勾选插件

2.登录失败

  • 检查 AppID 是否正确

  • Token 是否过期、格式是否正确

  • 控制台 ZIM 服务是否已开通

3.收不到消息

  • 确认双方都登录成功

  • 检查 receivePeerMessage 监听是否注册

  • 检查网络与连接状态

4.消息发送失败

  • 检查对方 userID 是否正确

  • 检查网络与连接状态

  • 避免超过发送频率限制（10 次 / 秒）

五、总结

基于 uni-app 跨端框架 + ZEGO ZIM 即时通讯 SDK，可快速实现稳定、低延迟的仿微信聊天功能。整套方案开发成本低、上线快，支持多端发布，非常适合社交、客服、协作类 APP 快速集成 IM 能力。

# uni-app # 实时互动
Logo
EazyDevelop社区

一站式 AI 云服务平台

更多推荐

cover

OpenClaw 零基础入门实战 零代码一键部署教程

avatar EazyDevelop社区

Midscene.js 原理拆解：它不是“自然语言点按钮”，而是一套会看屏幕的 UI 自动化运行时

摘要 Midscene.js 是一套基于视觉识别的UI自动化运行时系统，其核心创新点在于将传统UI自动化流程重构为四个层次：视觉理解、设备执行、结果校验和报告记录。与传统的基于元素定位的自动化工具不同，Midscene采用"先识别屏幕内容再操作"的模式，通过截图让AI模型判断目标位置，再转换为设备坐标执行操作。该系统特别适用于selector不稳定、自绘界面复杂、弹窗变化频繁以

avatar EazyDevelop社区
cover

OpenClaw 2.6.4 Windows 一键部署教程 本地 AI 智能体快速搭建

avatar EazyDevelop社区