必须用 IMLib + 原生插件桥接（或 JS SDK）组合方案，不能直接 npm install @rongcloud/im-kit——因其 Web 版依赖 document/window 等浏览器 API，而 uni-app 的 H5 端 DOM 受控、App 端无 DOM，会导致白屏、闪退或交互失效；IMLib 是纯能力层，需自行封装 UI 与状态管理，并在 App 端通过原生插件桥接融云 SDK 才能稳定运行。
直接上结论：uni-app 集成融云 IM，**必须用 IMLib + 原生插件桥接（或 JS SDK）组合方案，不能直接 npm install @rongcloud/im-kit**——因为官方 IMKit Web 版不兼容 uni-app 的运行时环境（document、window 不存在），而原生端又无法直接加载 Web IMKit 的 UI 组件。
uni-app 里为什么不能直接用 @rongcloud/im-kit
融云 Web @rongcloud/im-kit 是为标准浏览器设计的，依赖 document.createElement、DOM 事件监听、CSSOM 注入 等能力。uni-app 的 H5 端虽跑在浏览器里，但其 Vue 渲染层被 vue.runtime.esm.js 和 uni-app runtime 两层包裹，DOM 操作受控；App 端（iOS/Android）则完全无 DOM，JS 引擎是 JSCore/V8，@rongcloud/im-kit 会直接报 ReferenceError: document is not defined 或白屏。
常见错误现象：
- 打包 H5 后控制台疯狂报
Cannot read property 'appendChild' of null - App 端启动即闪退，日志显示
TypeError: undefined is not an object (evaluating 'document.body') - 即使强行 patch
document，消息列表也无法响应点击、长按等交互
正确做法：用 @rongcloud/imlib-next + 自封装消息收发逻辑
IMLib 是纯能力层 SDK，不依赖 DOM，只做连接、鉴权、收发、状态管理，天然适配 uni-app。你需要自己实现 UI 层（聊天窗口、会话列表、输入框），但好处是完全可控、可复用、多端一致。
实操建议：
- 通过
npm install @rongcloud/imlib-next --save安装（注意不是imlib，旧版已废弃） - 在
main.js或store/index.js中初始化单例：const im = new RongIMLib({ appKey: 'your-app-key' }) - 登录调用
im.connect(token)，务必用后端生成的 token（不能前端硬编码或调试 token） - 监听消息用
im.on('messageReceived', handler)，不要依赖imkit的内置监听器 - 发送文本消息示例：
im.sendMessage({ conversationType: 'PRIVATE', targetId: '1002', content: { content: 'hello' } })
App 端必须加原生插件，否则连不上
uni-app 的 App 端（iOS/Android）无法直接运行 Web SDK 的 WebSocket 连接逻辑，必须桥接到融云原生 SDK。否则你会看到 connect failed: network error 或反复触发 onConnectionStatusChange: DISCONNECTED。
关键步骤：
- 去融云官网下载对应平台的原生 SDK（
RongCloudIM.aar/RongCloudIM.framework） - 按 uni-app 插件规范封装成
unplugin（含android/src/main/java和iOS/RongCloudIMPlugin.m） - 插件内调用原生
RCIM.getInstance().connect(...)，把 token 透传进去 - JS 层通过
uni.requireNativePlugin('RongCloudIM')调用，收发消息走emit/on通信 - 别漏掉 Android 权限：
<uses-permission android:name="android.permission.INTERNET"></uses-permission>和ACCESS_NETWORK_STATE
token 失效和用户状态错乱是最常踩的坑
融云要求每次 connect 都用新 token，且 token 有效期默认 24 小时。但 uni-app 常见错误是：前端缓存 token、token 过期后没重拉、多设备登录没处理踢下线逻辑。
容易忽略的点：
- 后端生成 token 接口必须校验用户 session，不能裸暴露
/api/token?userId=xxx - 前端监听
onConnectionStatusChange，状态为KICKED_OFFLINE_BY_OTHER_CLIENT时要清本地 token 并跳转登录页 - App 端切后台再回来，
onReconnect可能失败，需主动调用reconnect()而非等自动重连 - 群聊消息未读数统计要用
getUnreadCount({ conversationType: 'GROUP', targetId: 'g1' })，不能靠前端累加
真正麻烦的从来不是“怎么连上”，而是“连上之后怎么保持稳定”——token 生命周期、多端状态同步、离线消息拉取时机、音视频信令与 IM 通道的耦合度，这些细节不提前对齐，上线后就是深夜排查 消息延迟 3 秒以上 或 群聊 A 发了 B 收不到 的循环。
