简介这份资源面向使用 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 groupIdcn.rongcloud.im/groupId artifactIdserver-sdk-java/artifactId version3.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. 后端签发 tokenMaven 环境下的最小可用实现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 帧、500kbps4G 下 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 能看到 BB 看不到 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 验证清单上线前必须跑的五个场景上线前我一般会跑一遍这五个场景确认没问题再发版场景操作预期单聊文本A 发 B 收消息即时到达未读数正确群聊图片群内发图所有人可见缩略图正常单人视频A 呼 B 接双方画面清晰挂断正常多人视频4 人进房不卡顿声音不重叠弱网重连切飞行模式再恢复自动重连消息不丢最后说个我自己的习惯每次接 IM 项目先写一个最小 demo 把 token、单聊、群聊、音视频各跑通一次再往业务里嵌。这样出问题时能快速定位是 SDK 问题还是业务代码问题。希望帮到你。本文还有配套的精品资源点击获取