React Native集成Notifee报native module not found错误如何解决

两个报错为连锁触发：Notifee native module not found是根因，原生依赖加载失败会中断JS bundle执行流程，导致AppRegistry.registerComponent未被调用，才抛出后续的应用未注册错误，和Metro启动路径无关，按以下步骤排查修复：

1. 清理全链路缓存，排除临时构建异常 #

安装新原生依赖后未清理缓存是最常见的偶发问题，按顺序执行以下操作：

• 终止所有正在运行的Metro服务、模拟器进程
• 在项目根目录执行清理与重装依赖命令：

# 移除现有依赖目录重新安装
rm -rf node_modules
# 使用yarn执行 yarn install，使用npm执行 npm install
yarn install

# 清理Android端构建缓存
cd android
./gradlew clean
cd ..

# 带缓存清理参数启动Metro服务
npx react-native start --reset-cache

• 新开终端窗口，重新执行npx react-native run-android构建运行应用，若仍报相同错误则进入下一步。

2. 修复依赖版本兼容问题 #

当前项目使用的React Native版本为0.63.4，属于较早的版本，你安装的@notifee/react-native@5.3.0、@react-native-firebase/*@14.11.0均不兼容该RN版本，是原生模块无法被识别的核心原因：

• @react-native-firebase/app、@react-native-firebase/messaging 14.x版本最低要求RN 0.65+，适配RN 0.63.x的最高兼容版本为12.9.3
• @notifee/react-native 5.x版本最低要求RN 0.66+，适配RN 0.63.x的最高兼容版本为3.0.4

执行以下命令替换为兼容版本：

# 卸载现有不兼容依赖
yarn remove @notifee/react-native @react-native-firebase/app @react-native-firebase/messaging
# npm用户替换为npm uninstall对应命令

# 安装兼容版本
yarn add @react-native-firebase/app@12.9.3 @react-native-firebase/messaging@12.9.3 @notifee/react-native@3.0.4

依赖安装完成后，重复第一步的全链路缓存清理、重新构建流程。

3. 校验Android端原生配置 #

若上述操作完成后仍报错，逐项检查Android端配置：

• 打开android/settings.gradle文件，删除手动添加的notifee、react-native-firebase相关include配置，RN 0.60+支持原生模块自动链接，手动重复配置会导致模块加载冲突
• 打开android/build.gradle文件，确认minSdkVersion配置不低于21，notifee与Firebase消息模块均要求最低API等级为21
• 打开android/app/src/main/AndroidManifest.xml文件，确认已添加通知必要权限：

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

• 若开启了ProGuard代码混淆，在android/app/proguard-rules.pro中添加对应规则，避免构建时将原生模块类移除。

4. 通知功能实现与验证 #

构建成功后，在应用入口文件（通常为index.js或App.js）中添加初始化逻辑即可正常使用通知功能：

import messaging from '@react-native-firebase/messaging';
import notifee from '@notifee/react-native';

// 创建默认通知渠道（Android 8.0+必需）
async function createNotificationChannel() {
  await notifee.createChannel({
    id: 'default',
    name: '默认通知渠道',
  });
}

// 申请通知权限
async function requestNotificationPermission() {
  const authStatus = await messaging().requestPermission();
  const isPermissionGranted =
    authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
    authStatus === messaging.AuthorizationStatus.PROVISIONAL;
  if (isPermissionGranted) {
    // 打印FCM推送token，可用于服务端推送测试
    console.log('FCM Token:', await messaging().getToken());
  }
}

// 配置前台消息展示逻辑
messaging().onMessage(async (remoteMessage) => {
  await notifee.displayNotification({
    title: remoteMessage.notification?.title,
    body: remoteMessage.notification?.body,
    android: {
      channelId: 'default',
    },
  });
});

// 执行初始化
createNotificationChannel();
requestNotificationPermission();

注意：Android模拟器需要使用带Google Play服务的镜像才能正常接收FCM推送，若模拟器无Google Play服务，建议使用真机测试通知功能。

内容的提问来源于stack exchange，提问作者Hakan Olgun