React Native Async Storage 在升级到 RN 0.75.1 后的 Kotlin 编译问题解析

问题背景

在 React Native 生态系统中，Async Storage 是一个常用的本地存储解决方案。近期有开发者反馈，在将 React Native 升级到 0.75.1 版本后，遇到了 Kotlin 编译失败的问题，具体表现为 :react-native-async-storage_async-storage:compileDebugKotlin FAILED 错误。

问题表现

开发者在使用 React Native 0.75.1 版本和 Async Storage 1.24.0 版本时，Android 构建过程中会出现 Kotlin 编译失败的情况。错误信息表明在编译 Async Storage 模块的 Kotlin 代码时出现了问题。

环境分析

从开发者提供的环境信息来看，问题出现在以下典型环境中：

• macOS 14.4.1 (Apple M1 芯片)
• Node.js 22.5.1
• React Native 0.75.1
• React 18.3.1
• Async Storage 1.24.0
• Android Studio 2024.1
• Java 17.0.12

可能的原因

1. Kotlin 版本不兼容：React Native 0.75.x 系列对 Kotlin 版本有特定要求，可能与 Async Storage 依赖的 Kotlin 版本存在冲突。

2. Gradle 配置问题：项目中的 Gradle 配置可能没有正确指定 Kotlin 版本或相关依赖。

3. 缓存问题：构建系统的缓存可能包含了旧版本的依赖或配置信息。

4. 新架构兼容性：虽然开发者表示没有启用新架构，但 React Native 0.75.x 的底层变更可能影响了库的兼容性。

解决方案

基本解决步骤

1. 清理项目：

   • 删除 node_modules 目录
   • 删除 yarn.lock 或 package-lock.json
   • 在 Android 目录下执行 gradlew clean

2. 重新安装依赖：

   • 运行 yarn install 或 npm install
   • 确保所有依赖版本正确

3. 检查 Gradle 配置：

   • 确保 build.gradle 中指定了正确的 Kotlin 版本
   • 检查 gradle.properties 中的相关配置

进阶解决方案

1. 明确指定 Kotlin 版本： 在项目的 android/build.gradle 文件中，显式指定 Kotlin 版本：

   ext {
       kotlinVersion = "1.9.24"
   }
   

2. 更新 Async Storage 配置： 在 gradle.properties 中添加：

   AsyncStorage_kotlinVersion=1.9.24
   AsyncStorage_next_roomVersion=2.6.1
   AsyncStorage_next_kspVersion=1.9.24-1.0.20
   

3. 检查依赖冲突： 使用 ./gradlew :app:dependencies 命令检查项目依赖树，查找可能的版本冲突。

预防措施

1. 版本兼容性检查：在升级 React Native 版本前，检查所有关键依赖的兼容性矩阵。

2. 渐进式升级：不要一次性升级多个主要版本，而是采用渐进式升级策略。

3. 使用版本锁定：在 package.json 中使用精确版本号而非语义化版本范围，避免意外升级。

4. 维护干净的构建环境：定期清理构建缓存和 node_modules，确保构建环境干净。

总结

React Native 0.75.x 版本引入了一些底层变更，可能导致与某些第三方库的兼容性问题。对于 Async Storage 的 Kotlin 编译问题，大多数情况下可以通过清理项目、明确指定 Kotlin 版本和更新相关配置来解决。开发者应该养成良好的版本管理习惯，并在升级前充分测试关键功能。

对于仍然遇到问题的开发者，建议创建一个最小化复现项目，这有助于更准确地定位问题根源。同时，关注 React Native 和 Async Storage 的官方文档和更新日志，可以提前规避许多潜在的兼容性问题。