终端 SDK 相关问题

最近更新时间:2026-09-22 15:46:45
我的收藏

TUIKit 源码是否支持 AndroidX?

TUIKit 最新源码已经支持 AndroidX。

出现 6013 SDK 未初始化错误?

如果出现 6013 SDK 未初始化错误,您可以尝试以下方式排查:
1. 查看是否没有登录成功就进行收发消息等其他操作;
2. 查看是否登录时被其它终端踢掉,IM SDK 默认一个账号仅能在一个终端上登录。处理方式请参考 多终端同时登录 文档;
3. Android 请关注库文件是否未能全部加载,或是使用过程中被系统回收。
4. 当开发者并没有调用 SDK initSDK 接口初始化 IM 时,也会出现此报错问题。

发送表情,消息列表显示为空、或者乱码?

即时通信 IM 不提供表情包,具体的解析需要自己对齐。
表情使用有两种方式:
一种是使用 V2TIMFaceElem 中的 index,标识表情的索引,例如 Android 和 iOS 两端都有同一套表情图,索引2为笑脸,index=2 就表示笑脸,两端发送和接收都显示同一张索引表情图片即可。
另一种是使用 V2TIMFaceElem 中的 data,例如表情图片是由字符串命名,smile 表示笑脸,可在 data 中存储 smile,iOS 和 Android 两端都通过 data 作为 key 找到对应表情图片进行显示。
另外也可以两个字段都使用,如 data 表示哪一套表情,index 表示这套表情的哪个索引,可以实现类似 QQ 的多种不同表情效果。甚至可以在 data 数据中存储更为复杂的数据结构,只要多端解析规则一致即可。

翻译 IM 消息,怎么剔除表情和 @ 消息?

1. 先把输入的文本过滤一遍,提取出不需要翻译的表情或者 at 信息并缓存起来,把需要翻译的设置给接口。
2. 等翻译结果返回后,再把缓存的不需要翻译的表情或者 at 信息一起组合起来

有时进行操作时返回错误码:10002?

在需要进行服务端验证的操作时,如果网络异常、超时或者票据切换失败,就会返回此状态码,遇到此状态码时稍后重试即可。

收发消息时,收到错误码 6200 或 6201?

返回此状态码时,是客户端在网络离线、超时或无网络访问时出现,6200 的定义为请求时没有网络,6201 的定义为响应时没有网络,遇到此状态码时,请检查网络或等待网络恢复后重试。

收发消息时返回错误码:20003?

请检查用户账号(UserID)是否已在腾讯云导入,当 UserID 无效或 UserID 未导入腾讯即时通信 IM 时,会返回此错误码。

语音消息播放语音时返回错误码:6010?

通常情况是语音消息超过了漫游保存有效期,请求失败导致,可 延长漫游消息时间 或获取语音文件到本地播放(已过期的文件无法恢复)。但不同版本的 SDK 支持延长历史消息存储时长的消息类型不同,详情请参见 消息存储。

账号鉴权时返回错误码 70001 或 70003 或 70009 或 70013?

70001:UserSig 已过期;70003:UserSig 解析失败;70009:UserSig 验证失败;70013:UserID 不匹配。详情可参见 错误码。

Web 端使用 IM SDK 时返回错误码-2或-5?

-2:Web 端请求服务器失败,通常为网络问题,Web 端使用 HTTP Long Polling 方式向服务端请求,网络存在问题时会返回此状态码,请检查网络或重试。
-5:登录操作未完成,SDK 未获取到服务器返回的 a2key 和 tinyID 时,直接调用其它接口会出现“tinyid 或 a2为空”的错误提示信息和-5的错误码。

在 armeabi 平台上 SDK 报"java.lang.UnsatisfiedLinkError: No implementation found for"错误该如何处理?

拷贝 imsdk 的 aar 里面的 jni/armeabi-v7a/libImSDK.so 到源码工程的 src/main/jniLibs/armeabi 目录里,并在 build.gradle 中加载即可。

上架 App Store 时,出现 x86_64, i386 架构错误该如何解决?

该问题是由于 App Store 不支持 x86_64, i386 架构引起的,具体解决方法如下:
1. 清空项目编译缓存:
2. 选择 Product > clean,按住 Alt 变成 clean build Folder...,等待操作完成。
3. 剔除 App Store 不支持的 x86_64 和 i386 架构:
4. 选择 TARGETS>Build Phases。
5. 单击加号,选择 New Run Script Phase。
6. 添加如下代码:
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and

# removes unused architectures.

find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"

EXTRACTED_ARCHS=()

for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done

echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"

echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"

done

7. 重新打包上传。

IM 各端 Demo/TUIKit 工程中演示用的表情包,开发者是否可以直接使用?

为了尊重版权,IM Demo/TUIKit 工程中默认不包含大表情元素切图。在正式上线商用前,请您替换为自己设计或拥有版权的其他表情包。请注意,下图所示的默认小黄脸表情包版权属于腾讯云,您可以通过升级至 IM 企业版套餐 免费使用该表情包。




会话列表同步规则?

getConversationList(拉取会话列表) 是异步拉取本地缓存的会话列表数据
1. 第一次登录成功后,IM SDK 内部会去同步服务端漫游会话和未读消息(此时本地暂无会话缓存数据)。
2. 首次登录,在漫游会话还没同步完成之前,调用 getConversationList 接口拉取本地会话列表,会返回空数据。
3. 会话同步完成后,SDK 会通过 V2TIMConversationListener -> onSyncServerFinish 回调告知上层(上层可以在收到此回调再去拉取会话)
4. 会话同步完成,对于本地缓存的会话有变更,也会通过 V2TIMConversationListener ->( onNewConversation | onConversationChanged) 回调告知上层。

应用切后台或息屏情况下客户端 IM SDK 会一直处于连接状态吗?

不会,切后台或息屏都有可能导致 IM 连接断开。IM 只有长连接保活,没有进程保活。主要原因是手机厂商对于应用处于后台运行的限制策略越来越严格。
当 App 应用切后台或处于前台息屏,由于手机操作系统回收机制的策略原因,应用进程被挂起导致 IM 连接断开。不过应用重新切回前台,只要进程没有改变,IM SDK 感知到网络变化会自动重连(推荐:前台可配合调用 doForeground 接口,可主动触发重连)。
SDK 重连动作会触发:V2TIMSDKListener-> onConnecting、onConnectSuccess、onConnectFailed 回调,告知上层当前 IM 连接状态。






Android 端 UIKit 接入,添加自定义消息,不需要显示默认边距,该如何操作?

方法一:在不需要显示内边距的 Holder -> layoutVariableViews 函数中,添加以下代码:
msgArea.setPaddingRelative(0, 0, 0, 0);
reactionArea.setPaddingRelative(0,0,0,0);

方法二:在 layoutVariableViews 函数最底部调用下面两个方法:
setMessageBubbleBackground(null);
setMessageBubbleZeroPadding();

IM SDK 是什么样的日志缓存策略?

IM SDK 的日志模块是使用了微信 MARS 的 Xlog,XLog 使用流式方式对单行日志进行压缩,压缩加密后写入作为 log 中间 buffer 的 mmap 中。使用 Xlog 方案,除非 io 损坏或者磁盘没有可用空间,基本可以保证不会丢失任何一行日志。
1. 日志先写内存映射文件.mmap3。
2. 每15分钟从 mmap3 flush 一次到本地 xlog 文件。
3. 如果内容大于100kB,直接 Flush。
4. 结束进程重新登录也会直接 Flush。
5. 本地缓存的日志文件只会保存7天。

调用 IM SDK API 接口,报 6014 错误,请问如何优化?

6014 是比较常见的问题,例如:登录失败、被踢、主动退出登录,导致当前 IM 处于未登录状态,后续调用 IM SDK 接口未重新登录都会报 6014 错误。
我们的建议是:在上层做下兜底逻辑,例如:将 IM 所有使用的接口 error 回调统一处理,如遇到 6014 报错统一做下 login 操作成功后再请求一次,让用户无感知。
SDK 也有提供以下两个 API,用于 login 接口调用的判重处理,防止重复调用:
1. getLoginStatus():获取当前登录状态,如果登录状态为已登录或登录中,则上层无需调用 login 接口重复登录,仅无登录状态下调用即可(特例:如果是 UserSig 过期,那么可在 UserSig 过期回调内做登录操作,无需判断登录状态)。
2. getLoginUser():获取当前已登录的 UserID,如果当前已登录的 UserID 与需要业务层登录的 UserID 不一致,可重新登录,否则过滤不处理。

IM SDK 主动获取各类资料的缓存时长是否有限制?

主动获取群资料:默认1小时缓存时长。
主动获取群成员:默认1小时缓存时长。
主动获取用户资料:默认10分钟缓存时长。

IM SDK 重连策略是怎样的?

网络状态发生变更时,IM SDK 会自动重连。重连最多重试 6 次,最长要一分钟左右;如果 3 分钟左右 SDK 多种重连方式均失败则暂停继续重连,主动调用 API 接口或感知网络变化会再次触发重连。
IM SDK 有自己的一套长连接保活的逻辑,接入层一般不需要关注重连动作,正常调用接口就好。

为什么 GitHub 里下载的 Demo 的 TUI 组件代码和 pod ‘TUIXXX’ 集成的代码不一样?

GitHub 里下载的 Demo 先 pod update,再对比看看。

冷启动 App 后首次拉取好友申请列表,有一定概率会报错提示未登录,打印登录状态是登录中,是什么问题?

除获取会话列表、拉取历史消息这两个接口以外,SDK 的各项功能接口必须在登录成功后才能调用。

IM 运行报冲突:Multiple commands produce '/Users/apple/Library/Developer/Xcode/DerivedData/xxx/Build/Products/Debug-iphonesimulator/xxx.app/Frameworks/ImSDK_Plus.framework',该如何解决?

导致报冲突的原因通常是集成了两个或者以上的 IM SDK,只保留一个即可,常见情形:
1. 客户单独集成 TXIMSDK_Plus_iOS 后,又集成 TUI 组件,通过 TUI 组件又集成了 IM SDK,编译报冲突。
解决:这种情况可以将单独集成的 TXIMSDK_Plus_iOS 去掉。
2. 之前集成了 TUIChat、TUIConversation、TUICore 等非音视频相关的 TUI 组件,通过依赖集成进入到 TXIMSDK_Plus_iOS;后又集成了 TUICallKit、TUIRoomKit 或者 TUILiveKit 等音视频相关的组件,这些组件依赖集成了 TXIMSDK_Plus_iOS_XCFramework,集成后编译也会报冲突。
解决:TUIChat、TUIConversation、TUICore 等非音视频相关的 TUI 组件使用 DevelopPods 源码集成 时,可以确认下 .podspec 文件是否依赖 IM SDK,例如 TUICore.podspec 里依赖的是 TXIMSDK_Plus_iOS 的话,可以改成 TXIMSDK_Plus_iOS_XCFramework(和音视频依赖的 IM SDK 统一),然后 pod update。
TUIChat、TUIConversation、TUICore 等非音视频相关的 TUI 组件直接 pod 拉下来的可以尝试 pod update 都更新至最新版本。

报错:Upload Symbols Failed: The archive did not include a dSYM for the lmSDK Plus.framework with the UUiDs[B8B90567-F276-334A-8937-4D327A49AB4C1]. Ensure that the archive's dSYM folder includes a DWARF filefor lmSDK Plus.framework with the expected UUlDs.

Xcode 16 报的警告,不影响打包可先忽略。

iOS 端和 Android 端登录同一账号在线,Web 端和 iOS 端登录同一账号在线,接收通话邀请的场景下,一端挂断,另一端没有退出通话邀请界面,如何处理?

多端登录的处理需要客户调用 enableMultiDeviceAbility 接口才能开启,也需要 开通对应套餐包。

报错 Error: The pod "TXIMSDK_Plus_iOS_XCFramework," required by the plugin "tencent_cloud_chat_push" requires a higher minimum iOS deployment version than the plugin's reported minimum version. To build, remove the plugin "tencent_cloud_chat_push", or contact the plugin's developers for assistance. Error running pod install. Error launching application on iPhone 16 Pro.

解决方法:
1. 打开编译器控制台,进入 iOS 目录:cd ios。
2. 删除 Podfile.lock 或 pod.lock 文件(如果存在)。
3. 执行 pod 更新命令:pod repo update 或 pod install --repo-update。
4. 重新运行项目。
报错原因:
Flutter 中依赖的某个插件版本,本地 CocoaPods 缓存无法检测下载,需要更新。

Flutter 使用多引擎模式,当某个引擎 detach 的时候,会把 IM SDK 的所有 channel 都释放,导致所有引擎都无法使用?

IM Flutter SDK 8.7.7201 版本已优化多引擎支持。

在 iOS 上运行官网 IM Flutter Demo 报如下错误怎么办?

Swift Compiler Error(Xcode): Cannot find type 'PhoneNumber/Users/xia/.pub-cache/hosted/pub.dev/libphonenumber_plugin-.3.3/ios/Classes/SwiftLibphonenumberPlugin.swift:6:24 Could not build the application for the simulator. Error launching application on iPhone 15.

原因:iOS 项目用到了库 libphonenumber_plugin,其中依赖了 PhoneNumberKit 的最新版本。但 PhoneNumberKit 的最新版 4.0.0 是 breaking API change,其中做了改动 “renames the class PhoneNumberKit to PhoneNumberUtility“。libphonenumber_plugin 尚未针对该变动做适配,无法找到 PhoneNumberKit 而报错。
解决方法:将 libphonenumber_plugin 中依赖的 PhoneNumberKit 降级到旧版本 3.8.0。



Podfile 里这样改即可:


使用官方的 UI 库,长按消息底部操作栏出现 UI 显示异常?


V1 的组件是用的 material2 的样式来做的,新版 V2 是基于 material3 的。现在 Flutter 新项目默认用的是 material3。
应用一旦指定样式,全局生效,不能在组件中单独指定。
在 main.dart 入口处,MaterialApp 中指定 useMaterial3: false。两者在一些界面参数上有区别。
解决方案1:客户需在 MaterialApp 里指定下使用 material2 样式,不可以使用 material3 样式:useMaterial3: false。
解决方案2:如果客户坚持用 material3,需从 pub 上(建议)或者 GitHub 上下载源码,自行处理 material3 的适配。

UIKit-V1 发送视频消息,视频封面很模糊,如何解决?

体验问题,视频截图是用的第三方库 fc_native_video_thumbnail,看下是不是可以有参数调整。
Width 和 Height 改大一点,例如:从 128 改为 1280。

运行 iOS 模拟器时报错 CocoaPods not installed or not in valid state,但其实 CocoaPods 安装正常,是什么原因?

按照以下顺序,重新设置一下项目:
1. flutter clean
2. flutter pub get
3. Reload Android Studio
4. flutter run
点击查看 参考文档。

Flutter web 运行,一开始初始化的时候就报错:

TypeError: Cannot read properties of undefined (reading 'create')
packages/tencent_cloud_chat_sdk/web/manager/im_sdk_plugin_js.dart 134:27 initTim
packages/tencent_cloud_chat_sdk/web/manager/im_sdk_plugin_js.dart 148:14 initWebTim
packages/tencent_cloud_chat_sdk/web/manager/v2_tim_manager.dart 108:21 initSDK
packages/tencent_cloud_chat_sdk/tencent_cloud_chat_sdk_web.dart 171:26 initSDK
解决方案:点击查看 参考文档。

Flutter IM Demo 怎么打 Web 应用包后,在手机上运行?

点击查看 参考文档。

报错 FAILURE: Build failed with an exception.

* What went wrong:
A problem occurred configuring project ':better_player_plus'.
> Could not create an instance of type com.android.build.api.variant.impl.LibraryVariantBuilderImpl.
> Namespace not specified. Specify a namespace in the module's build file. See https://d.android.com/r/tools/upgrade-assistant/set-namespace for information about setting the namespace.
解决方案1:升级插件版本(推荐)​​
修改:
pubspec.yaml:
dependencies:
better_player_plus: ^1.0.8
解决方案2:手动注入命名空间​
1. 找到插件的 Android 模块构建文件:
路径:<项目目录>/android/src/main/build.gradle
或通过缓存路径:C:\\Users\\你的用户名\\.gradle\\caches\\.../better_player_plus/../android/build.gradle
2. ​在 Android 块内添加命名空间:
android {
namespace "uz.shs.better_player_plus" // 具体值参考库的包名
// 其他配置...
}


Flutter V1 UIKit 组件接入,开启网络 URL 解析预览,某种链接内容解析出现乱码,如何解决?


解决方案1:源码引入 tencent_cloud_chat_uikit 组件。



解决方案2:将 link_preview_generator_for_us 引入方式改成如下方式:
link_preview_generator_for_us:
git: https://github.com/Junkmer/link_preview_generator_for_us.git




Flutter V1 UIKit 接入,怎么全局开启头像显示的圆角角度?




可通过设置 TIMUIKitConfig.defaultAvatarBorderRadius 处理。







IM Flutter Demo 选择 web 浏览器运行报如下错误:Finished with error: Failed to bind web development server: SocketException: Failed to create server socket (OS Error: Failed to start accept), address = localhost, port = 63480




解决方法1:打开 Android Studio 在如下截图位置添加以下内容:--web-hostname=127.0.0.1。






解决方法2:如果是通过 terminal 命令工具运行,通过如下方式:flutter run -d chrome --web-hostname=127.0.0.1。

Flutter Vivo 离线推送,Vivo 消息收不到,控制台工具报错 10302,如何处理?




解决方法:上线后要改成正式推送。




V1 UIKit 5.0.0 及以上版本在 Flutter 3.24.x 版本上运行不成功?

UIKit-V1 在 Flutter 3.29.0 需要最新的 5.0.0版本,依赖的 extended_text: ^15.0.0。
UIKit-V1 最新的 5.0.0版本如果要在 Flutter 3.24.3运行,需要修改 UIKit 源码依赖 extended_text: ^14.0.0。

运行 Flutter Demo 报关于 better_player_plus 错误?




将 better_player_plus 升级至 better_player_plus: ^1.0.8。

Flutter IM SDK 接入后,在 Android、iOS、macOS 和 Windows 都运行正常,但仅在 Web 平台运行报错,报错内容如下:pub-cache/hosted/pub.dev/tencent_cloud_chat_sdk-8.6.7040/lib/native_im/bindings/native_imsdk_bindings_generated.dart:996:19: Error: 'Pointer' isn't a type. ffi.Pointer<ffi.Void>)>>('DartFindMessages');,该如何解决?

Flutter V1 UIKit Demo,选择 Android 平台运行 报如下错误:FAILURE: Build failed with an exception.

FAILURE: Build failed with an exception.
* What went wrong:
Could not open cp_settings generic class cache for settings file 'E:\\FlutterProject\\WorkProjects\\v1_demo_and_uikit\\v1_chat-demo-flutter\\android\\settings.gradle' (C:\\Users\\Administrator\\.gradle\\caches\\8.1.1\\scripts\\5f461bs4vludhoc0tr427ffwx).
> BUG! exception in phase 'semantic analysis' in source unit '_BuildScript_' Unsupported class file major version 65
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
* Get more help at https://help.gradle.org
BUILD FAILED in 1s

原因:
Unsupported class file major version 65(​​版本 65​​ 对应的是 ​​Java 21​​(Java 每个版本都有一个 class 文件版本号))。
项目使用了过旧的 Gradle 版本或系统安装了高于项目支持的 Java 版本。
解决方法:
在项目的 android/gradle.properties 文件中添加:
org.gradle.java.home=你的 JDK 路径(建议使用 jdk17)
示例:
Windows: org.gradle.java.home=C\\:\\\\Program Files\\\\Java\\\\jdk-17.0.2
macOS/Linux: org.gradle.java.home=/Users/xxxx/Downloads/jdk-17.0.2.jdk/Contents/Home

HarmonyOS 切后台断连,再切回前台 SDK 重连耗时久,要如何解决?

原因:因应用切回前台时,没有主动调用 IM SDK API 接口主动触发重连,导致耗时久。
解决方法:在 HarmonyOS 工程中对应位置参考以下截图对应位置添加 SDK 两个 API,用于主动触发重连。




注册 Token 失败,报错1000900010,如何解决?

参考 鸿蒙官网错误码。提醒:使用自动签名,是不行的,需改成手动签名。

集成鸿蒙推送成功了,安卓、iOS 给鸿蒙发消息,收不到推送?

其他平台发消息代码里面,要 setHarmonyCategory。