React Native v0.68构建报错:react-native-async-storage配置失败

核心根因定位 #

从构建日志可直接定位两个互相关联的触发点：

• 全链路Android Gradle插件（AGP）版本不统一：构建阶段明确提示无法识别included builds的AGP版本，要求所有子项目使用相同版本AGP，其中@react-native-async-storage/async-storage模块内置的AGP版本和主项目版本不匹配，是触发后续类加载错误的核心原因
• 构建缓存损坏：jetifier迁移、之前的异常构建中断，导致async-storage模块对应的Gradle编译缓存、node_modules下的模块文件出现损坏，无法正常加载node_modules/@react-native-async-storage/async-storage/android/build.gradle对应的编译类文件
• 额外注意：日志中提示的Gradle弃用特性警告是RN0.68版本的已知兼容提示，不会直接导致本次构建失败，无需优先处理

分步修复操作 #

按以下顺序执行操作，不要跳步：

1. 对齐全项目AGP版本
   • 打开项目根路径下android/build.gradle文件，找到dependencies闭包内classpath("com.android.tools.build:gradle:xxx")对应的版本号，RN0.68默认配套版本为7.0.4，如果未手动修改过配置直接用这个版本号即可
   • 打开node_modules/@react-native-async-storage/async-storage/android/build.gradle文件，将文件内声明的AGP版本替换为和主项目完全一致的版本号，不要修改该文件内的其他配置项
   • 若后续构建提示其他原生模块存在相同AGP版本不匹配问题，按同样逻辑替换对应模块的AGP版本即可
2. 全量清理损坏缓存
   • 在项目根目录执行以下命令，清理损坏的依赖文件：

     # Windows环境可在PowerShell或Git Bash中执行
     rm -rf node_modules
     # 根据使用的包管理器删除对应锁文件，不要全删
     rm package-lock.json # npm用户执行
     # rm yarn.lock # yarn用户执行
     # rm pnpm-lock.yaml # pnpm用户执行
     # 重新安装依赖
     npm install # 替换为自己使用的包管理器安装命令
     

   • 进入android目录清理Gradle构建缓存：

     cd android
     # Windows环境下如果./gradlew执行失败，替换为gradlew.bat
     ./gradlew clean
     # 清理全局Gradle构建缓存
     rm -rf ~/.gradle/caches/build-cache-*
     

3. 手动执行AndroidX迁移
   回到项目根目录，手动触发jetifier全量迁移，避免自动迁移过程中出现文件遗漏：

   npx jetify
   

4. 验证构建结果
   执行带完整警告提示的构建命令，确认修复结果：

   react-native run-android --warning-mode all
   

修复验证标准 #

• 构建初始化阶段不再弹出「无法检测included builds对应的AGP版本」提示
• 配置:@react-native-async-storage_async-storage项目阶段不再抛出类加载失败异常
• 构建流程正常走完，APP可自动安装到已连接的设备/模拟器上

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