用途：面向使用 CometChat Flutter UIKit v5 的开发者在调试时，按症状定位可能原因并给出修复方向，同时提供发布前校验清单。
主要内容按类别组织：初始化与登录（init 未完成导致登录静默挂起、appId 未设置、region 必须小写如 'us'/'eu'/'in'、需设置 subscriptionType）；UI 与主题（主题色板应在 didChangeDependencies() 缓存而非 build()，色板中 white/black/transparent 不随明暗模式变化）；GetX 控制器生命周期（避免提前 Get.find()、重复实例与越权 Get.delete()）；监听器与事件（唯一 ID、dispose() 中移除、用 CometChatUIKit.sendTextMessage() 触发 ccMessageSent）；通话（设置 CallNavigationContext.navigatorKey、注册 CometChatCallingExtension、申请相机/麦克风权限）；推送（登录后注册、登出前注销令牌，VoIP 需开启后台模式并用 @pragma('vm:entry-point')）；Android 构建（ProGuard keep 规则、minSdk 26、AndroidX）；iOS 构建（Info.plist 权限描述、pod repo update）；回调签名错误（各组件 onItemTap 是否含 BuildContext）；v5/v6 漂移检测（出现 flutter_bloc、Equatable、ServiceLocator、BuilderSettings 等即误用 v6 模式）。
使用方式：按症状或错误信息在对应表中查找原因与修复项，并核对校验清单。
限制：资料仅列出症状、原因与修复要点，未提供完整代码、版本兼容范围或收费信息。