uniapp 对接融云 IM 与 RTC：单聊群聊音视频全链路落地实践

简介：这份资源面向使用 uniapp 开发即时通讯功能的移动端开发者，重点解决融云 IM 在聊天、群聊及单多人音视频通话场景下的对接难题。内容涵盖消息监听、消息撤回回执、分页获取聊天记录、会话未读数统计、免打扰时间设置、输入状态消息以及单人/多人语音视频通话等核心接口的实现思路，并附有后端 token 生成方案与 maven 环境配置说明，适合具备一定 uniapp 与 Java 基础的中级开发者参考。压缩包共 651 个文件，以 png 截图、h 头文件、js 脚本、json 配置及 aar 库文件为主，另含 plist、modulemap、strings 等原生工程资源，整体约 79.12MB，目录结构完整。资源内提供可直接运行的 demo，配合文档能帮助读者快速理解融云 SDK 的集成流程与调用方式。目前已有 2639 人学习下载，可作为 IM 与音视频模块开发时的实操参考。

1. uniapp 对接融云 IM：从单聊群聊到多人音视频，一条能跑通的落地路径

如果你正在做一个 uniapp 项目，需求列表里同时出现了「单聊」「群聊」「语音通话」「视频通话」，那大概率绕不开融云这套 IM + RTC 方案。我最近刚把一个类似需求从零跑通，踩的坑不算少，但整体链路是清晰的：后端签发 token，前端 uniapp 接入 SDK，单聊群聊走 IM 通道，音视频走 RTC 通道，两条线共用一套用户体系。这篇文章不讲虚的，只讲我实际怎么搭、参数怎么配、哪里容易翻车。适合两类人：一是第一次接 IM 的 uniapp 开发者，二是已经用过 IM 但没碰过音视频、想一次把两条链路打通的人。下面按「环境准备 → token 签发 → 单聊群聊 → 音视频 → 避坑 → 进阶」的顺序展开，每一步都给出可复制的代码和参数说明。

2. 环境准备与 SDK 选型：为什么 uniapp 接融云要分两条线

2.1 IM 和 RTC 是两套 SDK，别混着引

融云在 uniapp 侧提供的是两套能力：IM 负责消息收发、会话管理、群组管理；RTC 负责音视频通话。很多新手以为引一个包就全搞定，结果发现音视频接口根本找不到。常见做法是分别引入 IM SDK 和 RTC SDK，两者初始化时机不同，IM 可以早初始化，RTC 建议在进入通话页前再初始化，避免占用麦克风摄像头权限。

在 uniapp 里，IM 一般通过原生插件或 npm 包接入，RTC 同理。我一般会先确认项目用的是 uni-app 的 Vue2 还是 Vue3，因为插件市场里部分插件对 Vue3 支持不完整。如果是 Vue3，优先找明确标注支持 Vue3 的版本，否则会在mounted阶段报undefined。

2.2 后端环境：Maven 项目里加融云服务端依赖

后端 token 签发必须用融云服务端 SDK。以 Java Maven 项目为例，在pom.xml里加依赖，注意版本要和融云服务端 API 兼容。下面是我用的配置片段：

<!-- 融云服务端 SDK，用于签发 token 和调用服务端 API --> <dependency> <groupId>cn.rongcloud.im</groupId> <artifactId>server-sdk-java</artifactId> <version>3.2.0</version> </dependency>

加完后执行mvn clean install，如果拉不下来，检查仓库地址是否配了融云的镜像。参数说明：groupId和artifactId是固定的，version建议用官方文档标注的稳定版，不要盲目追新。我见过有人用 4.x 版本结果和前端 SDK 协议对不上，消息能发但收不到。

2.3 前端 uniapp 项目初始化顺序

前端这边，先npm install对应 SDK，然后在main.js里做一次全局初始化。初始化只需要 appKey，这个从融云控制台拿。注意 appKey 分测试环境和生产环境，别混用，否则 token 校验会失败。

// main.js 中初始化 IM SDK import RongIM from '@/utils/rong-im.js' // 封装后的 IM 实例 RongIM.init({ appKey: '你的 appKey', // 控制台获取，测试和生产分开 debug: true // 开发阶段打开日志，上线关掉 })

逻辑说明：init只做一次，放在main.js里保证全局可用。debug打开后控制台会打印连接状态和消息回执，排查问题时非常有用，但上线前务必关掉，否则日志量很大。

3. 后端签发 token：Maven 环境下的最小可用实现

3.1 token 签发的三个必调参数

融云 token 签发接口核心就三个参数：userId、name、portraitUri。userId是你系统里的唯一用户标识，建议用业务 ID 而不是手机号，避免泄露。name是昵称，portraitUri是头像地址，这两个可以为空，但为空时对方收到消息会显示默认头像和 ID。

下面是我在 Spring Boot 里写的签发方法：

// TokenService.java import cn.rongcloud.im.server.RongCloud; import cn.rongcloud.im.server.models.TokenResult; public class TokenService { private static final String APP_KEY = "你的 appKey"; private static final String APP_SECRET = "你的 appSecret"; public String getToken(String userId, String name, String portraitUri) throws Exception { RongCloud rongCloud = RongCloud.getInstance(APP_KEY, APP_SECRET); // 第三个参数为头像，没有就传空字符串 TokenResult result = rongCloud.user.register(userId, name, portraitUri); if (result.getCode() == 200) { return result.getToken(); } throw new RuntimeException("token 签发失败: " + result.getErrorMessage()); } }

逻辑说明：register方法在用户不存在时会自动注册并返回 token，存在时直接返回新 token。参数userId长度建议控制在 64 字符以内，name不要带特殊字符，否则部分客户端解析会出问题。返回的code为 200 才算成功，其他情况按错误信息排查。

3.2 把 token 接口暴露给 uniapp 前端

前端登录后需要拿 token 去连接 IM。我一般会写一个/api/im/token接口，前端用uni.request调用。注意这个接口要带业务登录态校验，不能裸奔，否则任何人都能拿 token。

// 前端获取 token uni.request({ url: 'https://你的域名/api/im/token', method: 'GET', header: { 'Authorization': 'Bearer ' + uni.getStorageSync('token') }, success: (res) => { if (res.data.code === 200) { uni.setStorageSync('imToken', res.data.token) // 拿到 token 后连接 IM RongIM.connect(res.data.token) } } })

参数说明：Authorization是你业务系统的登录凭证，和 IM token 是两回事，别搞混。拿到 IM token 后存本地，后续重连直接用，不用每次都请求接口。

3.3 连接状态监听与重连策略

IM 连接不是一劳永逸的，网络切换、App 切后台都会断。必须监听连接状态，断了自动重连。我一般会设一个重连计数器，超过 5 次就提示用户手动检查网络。

// 监听连接状态 RongIM.addConnectionStatusListener({ onChanged: (status) => { if (status === 'TOKEN_INCORRECT') { // token 失效，重新走接口获取 refreshTokenAndReconnect() } else if (status === 'NETWORK_UNAVAILABLE') { // 网络不可用，等网络恢复后重连 uni.onNetworkStatusChange((res) => { if (res.isConnected) RongIM.reconnect() }) } } })

逻辑说明：TOKEN_INCORRECT说明 token 过期或被顶掉，必须重新签发。NETWORK_UNAVAILABLE不要盲目重试，等网络恢复事件再触发。这里有个坑：重连时如果 token 已经失效，会陷入死循环，所以要先刷新 token 再重连。

4. 单聊与群聊：消息收发、会话管理和群组操作

4.1 单聊消息发送与接收的最小闭环

单聊就是两个 userId 之间的会话。发送消息用sendMessage，接收用全局消息监听。下面是最小闭环：

// 发送单聊文本消息 const msg = { conversationType: 'PRIVATE', // 单聊 targetId: '对方 userId', messageType: 'RC:TxtMsg', content: { content: '你好' } } RongIM.sendMessage(msg).then((res) => { console.log('发送成功', res.messageId) }) // 全局接收消息 RongIM.addMessageListener({ onReceived: (message) => { if (message.conversationType === 'PRIVATE') { // 更新会话列表和未读数 updateConversation(message) } } })

参数说明：conversationType单聊固定PRIVATE，群聊是GROUP。messageType文本是RC:TxtMsg，图片是RC:ImgMsg，自定义消息用RC:CustomMsg加自己的 content 结构。targetId单聊是对方 userId，群聊是群 ID。

4.2 群聊的创建、加入和消息收发

群聊比单聊多一步群组管理。创建群用createGroup，加入群用joinGroup。群消息发送和单聊几乎一样，只是conversationType改成GROUP。

// 创建群组 RongIM.createGroup({ groupId: '自定义群 ID', // 不传则自动生成 groupName: '项目讨论组', memberIds: ['user1', 'user2'] // 初始成员 }).then((res) => { console.log('群创建成功', res.groupId) }) // 发送群消息 RongIM.sendMessage({ conversationType: 'GROUP', targetId: '群 ID', messageType: 'RC:TxtMsg', content: { content: '大家好' } })

逻辑说明：groupId建议用业务 ID，方便和你的系统关联。memberIds最多一次传 100 个，超了要分批。群消息接收和单聊共用onReceived，通过conversationType区分。

4.3 会话列表与未读数同步

会话列表是 IM 的门面，必须实时更新。融云提供getConversationList拉取，但更推荐用本地数据库加监听的方式，避免每次进首页都请求网络。

// 获取本地会话列表 RongIM.getConversationList({ count: 100 // 一次最多拉 100 条 }).then((list) => { this.conversations = list.map(item => ({ targetId: item.targetId, name: item.conversationTitle, unread: item.unreadMessageCount, time: item.sentTime })) }) // 监听未读数变化 RongIM.addUnreadCountListener({ onChanged: (count) => { uni.setTabBarBadge({ index: 1, text: count > 99 ? '99+' : String(count) }) } })

参数说明：count不要设太大，100 足够首屏。未读数监听要记得在页面销毁时移除，否则会内存泄漏。这里有个血泪经验：群消息的未读数默认是汇总的，如果要做「有人@我」单独提醒，需要解析消息里的mentionedInfo字段。

5. 单人与多人音视频通话：RTC 房间模型和参数调优

5.1 单人通话和多人通话的房间模型差异

融云 RTC 用房间模型，单人通话就是两人进同一房间，多人通话是多人进同一房间。区别在于：单人通话可以直接用call接口，多人需要先创建房间再逐个加入。我一般统一用房间模型，单人通话也走房间，代码复用率高。

// 加入 RTC 房间 RongIM.joinRTCRoom({ roomId: '房间 ID', // 单人通话用双方 userId 拼接，多人用群 ID userId: '当前用户 ID', mode: 'video' // 'audio' 或 'video' }).then(() => { // 加入成功，开始推流 RongIM.publishLocalStream() })

参数说明：roomId要全局唯一，单人通话建议用userId1_userId2排序后拼接，避免重复。mode决定是否开启摄像头，音频通话传audio可以省流量。

5.2 音视频参数：分辨率、帧率和码率怎么设

RTC 默认参数不一定适合所有网络。我一般会根据场景调：WiFi 下 640x480、15 帧、500kbps；4G 下 480x360、15 帧、300kbps；弱网下 320x240、10 帧、150kbps。

// 设置视频参数 RongIM.setVideoProfile({ resolution: '640x480', // 分辨率 frameRate: 15, // 帧率 bitrate: 500 // 码率 kbps })

逻辑说明：分辨率越高越清晰但越耗流量，帧率影响流畅度，码率决定画质下限。弱网下不要硬撑高参数，否则会卡顿甚至断流。这里有个玄学问题：部分安卓机在 640x480 下画面旋转 90 度，需要在推流前调setVideoOrientation。

5.3 通话邀请、接听和挂断的信令流程

音视频通话需要一套信令：邀请、接听、挂断。融云 IM 可以发自定义消息做信令，RTC 负责媒体流。我一般用RC:CustomMsg发邀请，对方收到后弹窗，接听则加入同一房间。

// 发起通话邀请 RongIM.sendMessage({ conversationType: 'PRIVATE', targetId: '对方 userId', messageType: 'RC:CustomMsg', content: { type: 'CALL_INVITE', roomId: '房间 ID', mode: 'video' } }) // 对方接听 RongIM.sendMessage({ conversationType: 'PRIVATE', targetId: '发起方 userId', messageType: 'RC:CustomMsg', content: { type: 'CALL_ACCEPT', roomId: '房间 ID' } })

参数说明：type自定义字段用来区分信令类型，roomId必须一致。挂断同理，发CALL_HANGUP后双方退出房间。注意信令消息不要存历史记录，发完即焚，否则会话列表会很乱。

6. 避坑与排查：这五个问题我几乎每次都遇到

6.1 坑一：token 签发成功但连接报 TOKEN_INCORRECT

现象：后端返回 token，前端connect后状态变成TOKEN_INCORRECT。原因通常是 appKey 和 appSecret 不匹配，或者 token 签发用的 appKey 和前端初始化用的不是同一个。解决：核对控制台两套环境的 key，测试环境用测试的，生产用生产的，别混。

6.2 坑二：群消息能发出去但对方收不到

现象：发送方显示成功，接收方无消息。原因多是接收方没加入群，或者群 ID 大小写不一致。解决：发送前确认双方都在群里，群 ID 统一用字符串且区分大小写。另外检查接收方的消息监听是否在连接成功后注册。

6.3 坑三：音视频通话一方有画面一方黑屏

现象：A 能看到 B，B 看不到 A。原因通常是 B 的摄像头权限没给，或者推流失败但没报错。解决：进入通话页前先请求权限，推流后监听onPublishStateChanged，失败就重试一次。安卓还要检查是否被其他 App 占用摄像头。

6.4 坑四：多人通话超过 4 人后卡顿严重

现象：3 人流畅，第 4 人进来开始卡。原因是默认码率没降，上行带宽不够。解决：超过 4 人时主动降分辨率和码率，或者改用混流模式，服务端合流后下发一路流，客户端压力小很多。

6.5 坑五：App 切后台再回来 IM 断连

现象：切后台几分钟，回来消息收不到。原因是系统回收了网络连接。解决：监听onShow时检查连接状态，断了就重连。RTC 同理，切后台要主动挂断或暂停推流，否则会被系统杀掉。

7. 进阶技巧：用自定义消息打通业务通知和通话记录

7.1 自定义消息的结构设计和解析

融云的自定义消息RC:CustomMsg是扩展业务的最佳入口。我一般用它做三件事：通话记录、订单通知、系统提醒。结构上统一用type区分，data放业务字段。

// 发送自定义消息 RongIM.sendMessage({ conversationType: 'PRIVATE', targetId: '对方 userId', messageType: 'RC:CustomMsg', content: { type: 'ORDER_NOTIFY', data: { orderId: '123', status: 'paid' } } }) // 接收时解析 RongIM.addMessageListener({ onReceived: (message) => { if (message.messageType === 'RC:CustomMsg') { const content = JSON.parse(message.content) if (content.type === 'ORDER_NOTIFY') { // 处理业务逻辑 } } } })

参数说明：type建议用大写加下划线，避免和融云内置类型冲突。data不要太大，超过 1KB 建议走业务接口拉取。

7.2 通话记录写入会话列表的两种方式

通话结束后，用户希望在会话列表看到一条「通话时长 00:32」的记录。两种做法：一是发一条自定义消息，二是本地插入一条伪消息。我推荐第一种，因为能同步到多端。

// 通话结束后发送记录消息 RongIM.sendMessage({ conversationType: 'PRIVATE', targetId: '对方 userId', messageType: 'RC:CustomMsg', content: { type: 'CALL_RECORD', data: { duration: 32, mode: 'video' } } })

逻辑说明：这条消息会正常进入会话列表，接收方也能看到。注意不要设置未读数，否则会打扰用户。可以在发送时把isCounted设为 false。

7.3 验证清单：上线前必须跑的五个场景

上线前我一般会跑一遍这五个场景，确认没问题再发版：

最后说个我自己的习惯：每次接 IM 项目，先写一个最小 demo 把 token、单聊、群聊、音视频各跑通一次，再往业务里嵌。这样出问题时能快速定位是 SDK 问题还是业务代码问题。希望帮到你。

本文还有配套的精品资源，点击获取