React Native安卓构建失败：Gradle缓存缺失文件报错解决

问题基础信息 #

• 项目类型：适配iOS/安卓双端的React Native应用
• 项目版本栈：React 18.0.0、React Native 0.69.0
• 开发环境：Gradle 7.4.2、Kotlin 1.5.31、JVM 18.0.1.1，运行于Mac OS X 12.1 x86_64系统

问题触发链路 #

• 前期尝试新增react-native-gesture-handler、react-native-reanimated、react-native-safe-area-context、@gorhom/bottom-sheet四个依赖时出现安装错误，更换替代依赖规避问题后，将代码完全回滚到新增依赖前的状态
• 排查前期依赖问题时，曾执行rm -r $HOME/.gradle/caches/清理Gradle缓存，当时操作可正常解决对应问题，未预判会引发后续异常
• 代码回滚完成后执行npm run android启动安卓端，构建直接失败

核心报错特征 #

Task :app:checkDebugAarMetadata执行失败，抛出大量java.nio.file.NoSuchFileException异常，提示用户目录下.gradle/caches/transforms-3/路径下上百个results.bin文件不存在

已验证无效的操作 #

• 重装Gradle
• 重装Android Studio及所有模拟器
• 执行gradle --build-cache
• 删除node_modules与package-lock.json后重新执行npm i安装依赖
• 清理React Native缓存、npm缓存
• 复制同环境正常运行同事设备上的.gradle/caches/transforms-3/目录到本地对应缓存路径
• 执行gradle cleanBuildCache返回「根项目不存在该任务」错误，无法执行

根因说明 #

1. 清理Gradle缓存时未同步终止后台驻留的Gradle Daemon进程，进程持有的旧缓存索引未释放，重新构建时会按照已失效的索引路径查找文件，触发文件不存在报错
2. 仅删除用户目录下的Gradle缓存，未清理项目目录下的.gradle缓存、build构建产物，旧的构建元数据与新生成的缓存不匹配
3. 当前使用的JVM 18版本与React Native 0.69.0存在官方未覆盖的兼容性问题，RN 0.69最高适配JDK 11版本，高版本JDK会导致AAR元数据校验、transform产物生成流程异常
4. 跨设备复制Gradle缓存无效：Gradle缓存条目绑定本地文件路径、用户权限、进程生成的唯一哈希，其他设备的缓存无法被本地Gradle进程识别
5. cleanBuildCache为旧版Android Gradle插件内置任务，新版AGP已移除该任务，执行报错属于正常现象，无需额外处理

修复步骤 #

1. 终止所有后台驻留的Gradle、Java进程，释放文件锁：

pkill -f gradle
pkill -f java

2. 彻底清理全链路Gradle缓存与旧构建产物，执行以下命令：

# 清理用户目录下Gradle残留
rm -rf $HOME/.gradle/caches/
rm -rf $HOME/.gradle/daemon/
rm -rf $HOME/.gradle/wrapper/dists/
# 清理项目侧Gradle缓存与构建产物
rm -rf <你的项目根目录>/android/.gradle
rm -rf <你的项目根目录>/android/app/build
rm -rf <你的项目根目录>/android/build

3. 将本地JDK版本切换为JDK 11（推荐使用Temurin 11发行版），配置完成后执行java -version确认输出版本为11.x，保证JAVA_HOME环境变量指向JDK 11的安装路径
4. 回到项目根目录重新执行构建：

npm install
cd android && ./gradlew clean
cd .. && npm run android

注意：首次重新构建时Gradle会重新下载所有依赖、生成transform产物，耗时会比常规构建久，属于正常现象，不要中途终止构建进程。

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