升级React Native项目至0.69.0版本时出现报错如何排查解决

问题场景 #

将React Native项目升级至0.69.0版本后，运行项目时出现异常报错，报错信息如下：

报错核心原因 #

• 基础环境版本不满足硬要求：RN0.69是首个强制要求Node.js版本≥16的正式版，同时iOS端要求CocoaPods版本≥1.11.3，Android端要求Gradle≥7.2、Android Gradle Plugin≥7.1.2，本地环境版本不达标会直接触发构建、运行阶段的异常。
• 原生启动逻辑未同步更新：0.69版本重构了双端启动流程，将原有分散在AppDelegate、MainActivity中的初始化逻辑抽离为RCTAppSetupUtils模块，升级时如果没有对齐官方模板更新原生端代码，会直接出现桥接加载失败、模块找不到的报错，和截图中的异常特征完全匹配。
• 依赖冲突：0.69已经内置react-native-codegen，如果项目手动安装了旧版codegen，或者第三方原生库引用了不兼容的codegen版本，会触发NativeModule注册冲突。另外部分带原生代码的第三方库未适配0.69版本（比如react-native-reanimated版本低于2.9.0），也会导致启动崩溃。
• 新架构配置误开：0.69版本新增了新架构开关入口，如果误将newArchEnabled设为true但没有完成新架构对应的依赖安装、编译配置，会直接导致运行时异常。

排查修复步骤 #

按以下顺序操作即可覆盖90%以上的0.69升级启动报错场景：

1. 校验本地基础环境版本
   执行命令核对版本，不符合要求的先升级：

   node -v # 输出结果必须≥16.0.0，推荐使用16.x LTS版本
   pod --version # iOS环境必须≥1.11.3，推荐1.11.3以上稳定版
   

   Android端手动核对两个配置：
   • 打开android/gradle/wrapper/gradle-wrapper.properties，确认distributionUrl对应的Gradle版本≥7.2
   • 打开android/build.gradle，确认com.android.tools.build:gradle依赖版本≥7.1.2
2. 全量清理旧构建缓存
   旧版本的编译缓存、依赖缓存是升级后报错的高频诱因，依次执行以下命令彻底清理：

   # 清理JS端缓存
   watchman watch-del-all
   rm -rf node_modules
   # 用项目实际使用的包管理器安装依赖，yarn就执行yarn install，npm就执行npm install
   yarn install
   rm -rf /tmp/metro-*
   
   # 清理Android端构建缓存
   cd android
   ./gradlew clean
   cd ..
   
   # 清理iOS端依赖和构建缓存
   cd ios
   rm -rf Pods Podfile.lock build
   pod install --repo-update
   cd ..
   

3. 对齐原生端模板代码
   对照RN0.69官方升级模板，逐行核对双端原生启动代码：
   • iOS端重点核对AppDelegate.h、AppDelegate.mm（注意0.69开始默认用mm后缀的实现文件，不再是m后缀）的初始化逻辑，补全RCTAppSetupUtils的导入和调用
   • Android端重点核对MainApplication.java/kt、MainActivity.java/kt的代码，删除旧版本的冗余初始化逻辑，对齐模板写法
4. 解决依赖冲突
   • 直接删除package.json中手动声明的react-native-codegen依赖，0.69及以上版本不需要手动安装该包
   • 如果第三方库间接依赖了不兼容的codegen版本，在package.json中添加配置强制对齐版本：

     // yarn用户添加resolutions字段
     "resolutions": {
       "react-native-codegen": "0.69.0"
     }
     // npm用户添加overrides字段
     "overrides": {
       "react-native-codegen": "0.69.0"
     }
     

   • 升级带原生代码的第三方依赖到支持RN0.69的版本，比如react-native-reanimated必须≥2.9.0，react-native-gesture-handler必须≥2.5.0，其他原生库可到对应仓库查看兼容性说明
5. 校验新架构开关配置
   分别打开android/gradle.properties和iOS端的Podfile，确认newArchEnabled配置为false，无明确需求不要提前开启新架构，开启后需要完成额外的编译配置才能正常运行。

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