uni-app+即构SDK实现即时通讯聊天如今大部分 App、小程序都离不开即时聊天功能。如果纯手写通讯逻辑，开发量大、

如今大部分 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” 平台，并填写项目名称，并点击创建即可

导入 SDK

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

方式一：从 ZEGO 官网下载

请参考下载页面，获取最新版本的 SDK 到本地，并将得到的 “zego-ZIMUniPlugin.zip” 文件解压缩。
将解压缩后的文件夹，直接复制到项目工程根目录下的 “nativeplugins” 文件夹，如果没有该目录，请手动创建。

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

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

单击 “购买（0元） for 云打包”，选择相应的项目导入。
单击 “下载 for 离线打包”，离线导入。
- 下载 SDK 到本地，并将得到的 “zego-ZIMUniPlugin.zip” 文件解压缩。
- 将解压缩后的文件夹，直接复制到项目工程根目录下的 “nativeplugins” 文件夹，如果没有该目录，请手动创建。

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

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

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

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

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

方式一： 请参考下载页面，获取最新版本的 JS 封装层到本地，并将得到的 “zego-ZIMUniplugin-JS.zip” 文件解压缩。
下载的 JS 封装层可以拷贝到 HBuilderX 的 “js_sdk” 目录中。（如无该目录，请创建一个）

方式二： 在插件市场的Zego ZIM 即时通讯原生插件（JS 封装层界面单击右侧的 “使用 HBuilderX 导入插件”。

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

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

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

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

3.1 制作自定义调试基座

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

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

打包成功后，控制台会收到 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 支持的消息类型如下：

表格还在加载中，请等待加载完成后再尝试复制

以下为发送单聊文本消息为例：客户端 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 回调接收。

四、常见问题与解决方案

插件导入后不生效

必须使用自定义调试基座
检查 nativeplugins 目录结构是否正确
确认 manifest.json 已勾选插件

登录失败

检查 AppID 是否正确
Token 是否过期、格式是否正确
控制台 ZIM 服务是否已开通

收不到消息

确认双方都登录成功
检查 receivePeerMessage 监听是否注册
检查网络与连接状态

消息发送失败

检查对方 userID 是否正确
检查网络与连接状态
避免超过发送频率限制（10 次 / 秒）

五、总结

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

uni-app+即构SDK实现即时通讯聊天