React Native CLI运行Xcode报错：A moduleName is required to create an RCTRootView

开发者阿泽

2026-7-2

解决RCTRootView缺少moduleName的Xcode报错

Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'A moduleName is required to create an RCTRootView'

以下是具体排查和解决步骤：

检查AppDelegate.m/AppDelegate.mm文件中的RCTRootView初始化代码，确保传入了正确的moduleName参数。正确的初始化示例：

RCTRootView *rootView = [[RCTRootView alloc] initWithBundleURL:jsCodeLocation
                                                      moduleName:@"YourAppName"
                                               initialProperties:nil
                                                   launchOptions:launchOptions];

这里的moduleName必须和你的React Native入口文件中注册的名称完全一致。

确认入口文件（通常是index.js或index.ios.js）里的AppRegistry注册名称与AppDelegate中的moduleName匹配，包括大小写：
```
AppRegistry.registerComponent('YourAppName', () => App);
```
若近期修改过项目名称或配置，清理Xcode缓存：
1. 使用Cmd+Shift+K清理当前项目构建文件
2. 打开Xcode设置（Xcode > Settings > Locations），找到Derived Data目录，删除对应项目的缓存文件夹
3. 重新构建项目
排查第三方依赖：部分第三方库可能存在错误创建RCTRootView但未传入moduleName的情况，尝试更新相关库版本，或检查其初始化代码是否合规。
若启用了React Native新架构，检查新架构初始化代码中是否正确传递了moduleName参数，确保配置与旧架构的moduleName保持一致。