React Native集成agora-react-native-rtm报AgoraRTM.prefix错误如何解决

TypeError: null is not an object (evaluating 'AgoraRTM.prefix') 是典型的React Native原生桥接模块加载失败问题，和JS层业务代码无关，不需要修改声网SDK内部的Swift/Java源码，核心原因是JS侧尝试读取AgoraRTM对象的属性时，这个从原生层导出的对象实际为null，常见触发场景如下：

• 安装带原生代码的依赖后，未重新编译原生安装包，仅靠Metro热重载/刷新无法加载新增的原生模块
• React Native自动链接失效，没有把声网RTM的原生模块注册到桥接列表中
• 平台侧基础配置遗漏，比如iOS未执行pod install、Android未把RTM包加入应用包列表
• 依赖版本不兼容：agora-react-native-rtm的大版本和当前项目的React Native版本不匹配，桥接接口协议不一致导致原生模块导出失败

按顺序操作即可：

1. 全量清理缓存并重新编译
   先停掉所有正在运行的Metro服务、模拟器/真机上的应用，执行以下命令清理所有缓存：

   watchman watch-del-all
   rm -rf node_modules
   # 用你项目对应的包管理器安装依赖
   yarn install # 或者 npm install
   rm -rf /tmp/metro-*
   # iOS 额外执行pod重装
   cd ios
   pod deintegrate
   pod repo update
   pod install
   cd ..
   

   清理完成后不要用热更新，直接执行全量编译命令重新装包：

   # Android
   npx react-native run-android
   # iOS
   npx react-native run-ios
   

   绝大多数场景下这一步就能解决问题。
2. 校验链接结果
   • Android端：打开android/app/src/main/java/[你自己的项目包名]/MainApplication.java文件，检查导入区是否存在import io.agora.rtm.RtmPackage;，同时检查getPackages()方法返回的包列表中是否包含new RtmPackage()，如果缺失手动补上即可。
   • iOS端：打开ios目录下后缀为.xcworkspace的项目文件，检查Pods目录下是否存在AgoraRtmKit相关依赖，如果不存在，排查pod install执行时的报错（大多是本地CocoaPods源配置问题），修复后重新执行pod安装即可。
3. 排查版本兼容问题
   核对你安装的agora-react-native-rtm版本的适配说明，确认其支持的React Native版本范围和你当前项目使用的RN版本匹配。注意1.x和2.x版本的agora-react-native-rtm桥接接口完全不兼容，跨大版本安装会直接导致原生对象导出为null。
4. 增加前置防御判断
   在初始化RTM客户端的逻辑前增加原生模块存在性校验，避免直接崩溃：

   import { NativeModules } from 'react-native';
   const AgoraRTM = NativeModules.AgoraRTM;
   if (!AgoraRTM) {
     throw new Error('AgoraRTM原生模块未正确加载，请检查依赖编译配置');
   }
   // 后续再执行RTM初始化、登录、发消息等逻辑
   

内容的提问来源于stack exchange，提问作者Bilal Yaqoob