SuperAPI AI 工具集

cometchat-react-native-troubleshooting

编程与开发

查看项目

更新于 10-21 20:29

技能介绍

用途

本技能用于诊断已损坏的 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 对照表。

首要步骤(按顺序)

  1. init 是否解析,login 在其后是否解析?记录两者。
  2. GestureHandlerRootView 是否在最外层且有 flex: 1?
  3. kit 组件的每个祖先是否都是 flex: 1?
  4. 上次原生变更后是否重新构建,而非重载?
  5. 每个发出的符号是否存在于目录中?

验证是否修复

  • 症状在真机上可复现地消失,而不仅在模拟器上。
  • 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/'