用途
本技能用于诊断已损坏的 CometChat React Native 集成。当出现错误但错误信息无法说明原因时(在 React Native 中这几乎是常态),可使用本技能。它基于 @cometchat/chat-uikit-react-native@5 与目录 rn-v5.json,文档位于 /ui-kit/react-native/troubleshooting。
配套技能 cometchat-react-native-core(安装、provider 链、init→login→render)被视为已读,此处不再重复。
前提与安装
无。
先读这一点:RN 故障通常指向错误的对象
React Native 缺陷难以阅读,源于三个特性:
- 原生模块在挂载(MOUNT)时失败,而非构建时——应用能启动,随后某个界面崩溃。
- 错误指向对等依赖,而非 CometChat——如 gesture-handler、svg、video。
- 未知属性被静默忽略——无错误,什么都不渲染。
因此“错误信息完全没提到 CometChat”并不能证明问题在别处。
症状 → 根因 → 修复
聊天界面空白,无错误
- 在 login() 解析前就渲染:用 loggedIn 标志门控渲染;init → login → render。
- initFromSettings() 失败:无法捕获——CometChatUIKit.initFromSettings() 会吞掉初始化错误(其 rejection 处理器为空操作),await/.catch() 看不到任何东西。改为断言下一步:await login(...)(它会 reject)或检查 await CometChatUIKit.getLoggedInUser();错误的 appId/region 会在此处表现为认证失败。
- 某个祖先节点不是 flex: 1:每个祖先都需 flex: 1;滚动列还需 minHeight: 0。
UI 渲染但触摸无响应
GestureHandlerRootView 缺失、不是最外层、或缺少 flex: 1。不会抛出错误。在裸 RN 上还需确认 import 'react-native-gesture-handler' 是 index.js 的第一行——顺序错误常在 debug 下正常、release 下崩溃。
聊天界面出现 NativeModule … null / “cannot read property of null”
原生对等依赖缺失或未链接。安装完整对等依赖列表(见 core),然后 pod install(裸 RN)或重新构建 development build(Expo)。Metro 重载不会拾取原生变更——需重新构建。
Android 构建失败,错误从不提及 CometChat
@react-native-async-storage/async-storage 必须为 ^2.1.2——Chat SDK 在加载时要求它,Calls SDK 对等要求 2.x。未固定版本会解析到 3.x,导致 npm install @cometchat/calls-sdk-react-native@5 以 ERESOLVE 失败。检查:npm ls @react-native-async-storage/async-storage。
Expo:在 Expo Go 中正常,直到打开聊天界面
Expo Go 无法加载自定义原生模块。使用 development build(npx expo run:ios)。无变通方法。
自定义视图不出现
RN 上插槽属性为 PascalCase——是 ItemView,不是 itemView。React 的大小写会被静默忽略:无错误,什么都不渲染。与属性名拼错属同类缺陷。
消息界面出现两个堆叠的头部
导航器的头部加上 CometChatMessageHeader。在该界面设置 headerShown: false。
键盘打开时输入框被隐藏
祖先链中某处有固定高度,或消息界面嵌套在标签导航器内导致标签栏重叠。将消息界面放在标签之上的堆栈中。
iOS 上发送消息抛错(React Native >= 0.87)
React Native 0.87 从核心移除了 InteractionManager,而 CometChatMessageComposer(kit 至 5.5.0)在其发送路径的四个 iOS 专属分支中仍调用 InteractionManager.runAfterInteractions()。点击发送会抛错,消息永远不离开设备。Android 不受影响;RN <= 0.86 也不受影响,那里该导出已弃用但仍可解析——这就是同一代码在旧应用上发送正常、在新模板上崩溃的原因。
出现位置与现象:
- dev build:Uncaught Error: InteractionManager has been removed from react-native core. Please refactor long tasks into smaller ones, and use 'requestIdleCallback' instead. in CometChatMessageComposer -> sendTextMessage
- release build:同一行显示 undefined -> TypeError: Cannot read property 'runAfterInteractions' of undefined
- CI:无任何提示——类型检查、打包和构建在两个平台都通过;只有真人点击发送才会看到。
在 kit 移除该调用之前,在 kit 加载前恢复一个最小实现——index.js 的第一个 import:
// interactionManagerCompat.js — delete when the kit stops calling InteractionManager.
const ReactNative = require('react-native');
const missing = () => {
try {
return !ReactNative.InteractionManager;
} catch {
return true; // RN >= 0.87 in __DEV__: the getter throws.
}
};
if (missing()) {
Object.defineProperty(ReactNative, 'InteractionManager', {
configurable: true,
get: () => ({
runAfterInteractions: (task) => {
const run = () => (typeof task === 'function' ? task() : task && task.gen && task.gen());
let settle;
const ran = new Promise((resolve) => { settle = resolve; });
const timer = setTimeout(() => { run(); settle(); }, 0); // resolve AFTER the task runs
return {
then: (onResolve, onReject) => ran.then(onResolve, onReject),
done: (onDone) => { ran.then(onDone); },
cancel: () => clearTimeout(timer),
};
},
createInteractionHandle: () => 0,
clearInteractionHandle: () => {},
setDeadline: () => {},
addListener: () => ({ remove: () => {} }),
}),
});
}
try/catch 之后立即出现 ReferenceError: Property '<name>' doesn't exist
Hermes 会丢失仅在同一个块中创建的闭包内读取的 catch (error) 绑定——catch (error) { setLogs((prev) => [describe(error), ...prev]) } 在 catch 首次运行时抛错,而先读取该值再使用的相同代码则正常。两种情况都能通过类型检查和打包。将捕获的值读入局部变量,再在闭包内使用该局部变量。
来电不响铃
- CometChatIncomingCall 挂载在某个界面内:在导航器之上挂载一次。
- 已安装 calls SDK 但未运行 pods:pod install / 重新构建——否则首次通话时崩溃。
- 未声明相机/麦克风权限:添加它们(见 calls),然后重新构建。
- 在模拟器上测试:模拟器无法采集相机或麦克风——使用真机。
通知从不送达
在 login() 解析前注册 · 平台常量错误 · token 轮换后未重新注册 · 缺少 google-services.json / GoogleService-Info.plist · iOS 模拟器。见 push。
某功能已“启用”但无变化
- 仪表盘已切换,代码属性未设置:AI 功能需要两者;属性默认关闭。
- 它在 v5 中已是核心:reactions 和 mentions 默认开启——无需启用。
- kit 自动渲染它:auto_rendered_ui 功能无需客户端代码。
某个符号无法编译
检查 catalogs/rn-v5.json。可能是 React 名称:UIKitSettingsBuilder、login(uid)、onItemClick、CometChatErrorBoundary、CometChatDetails、CometChatMessagePlugin。参见 core/references/docs-map.md 中的 React→RN 对照表。
首要步骤(按顺序)
- init 是否解析,login 在其后是否解析?记录两者。
- GestureHandlerRootView 是否在最外层且有 flex: 1?
- kit 组件的每个祖先是否都是 flex: 1?
- 上次原生变更后是否重新构建,而非重载?
- 每个发出的符号是否存在于目录中?
验证是否修复
- 症状在真机上可复现地消失,而不仅在模拟器上。
- npm run verify:fences:rn-v5 通过。
- 若修复涉及原生变更,干净构建仍可工作。
tsc --noEmit 在 UI Kit 内报告错误,而非你的应用
kit 的 package.json 中 main: "src/index" 并发布未编译的 .tsx——没有 lib/,也没有 types 字段。因此 tsc 会跟随 import 进入 kit 自身源码,在 node_modules/@cometchat/chat-uikit-react-native/src/*.tsx 下报告约 30 个错误,而你的代码是干净的。
skipLibCheck 无济于事(它只跳过 .d.ts,而这里没有),exclude: ["node_modules"] 也无济于事(TypeScript 仍会跟随 import)。Metro 会剥离类型,因此打包和应用正常——这只影响 CI 类型检查。将检查范围限定到自己的源码:
tsc --noEmit -p tsconfig.json 2>&1 | grep -v 'node_modules/@cometchat/'