React Native Async Storage 在开启新架构时的构建问题分析与解决方案

问题背景

在React Native生态系统中，Async Storage作为持久化存储解决方案被广泛使用。随着React Native新架构(Fabric)的推出，开发者在迁移过程中可能会遇到构建问题。本文针对一个典型问题进行分析：当开启新架构(IS_NEW_ARCHITECTURE_ENABLED=true)时，Android构建过程中出现的CMakeLists.txt文件缺失错误。

错误现象

开发者在构建React Native项目(版本0.73.6)时，Android构建系统报告以下错误：

[CXX1409] expected buildFiles file 'app-react/node_modules/@react-native-async-storage/async-storage/android/build/generated/source/codegen/jni/CMakeLists.txt' to exist

这个错误表明构建系统期望找到一个由代码生成器(codegen)创建的CMake配置文件，但该文件并未生成。

根本原因分析

这个问题主要与React Native新架构的构建流程有关：

1. 新架构的代码生成机制：React Native新架构使用代码生成器来自动创建原生模块的接口代码，包括JNI层和C++代码。

2. 构建顺序问题：在标准构建流程中，代码生成应该在编译开始前自动执行。但在某些情况下，这个步骤可能被跳过或执行顺序不正确。

3. 环境配置因素：项目中的Gradle插件版本、React Native CLI工具链版本以及JDK版本等都可能影响代码生成步骤的执行。

解决方案

临时解决方案

1. 手动触发代码生成： 在项目android目录下执行：

   ./gradlew generateCodegenArtifactsFromSchema
   

   这个命令会显式触发代码生成步骤，创建所需的CMakeLists.txt文件和其他接口代码。

2. 清理构建缓存： 有时需要删除android/app/.cxx目录来确保干净的构建环境。

长期解决方案

1. 检查项目配置：

   • 确保package.json中包含Async Storage依赖
   • 验证React Native CLI相关包版本是否兼容
   • 确认Gradle和Android Gradle插件版本匹配

2. 升级相关依赖： 保持@react-native-async-storage/async-storage、React Native以及相关构建工具为最新稳定版本。

3. 构建脚本调整： 在android/app/build.gradle中确保正确配置了新架构相关选项。

技术深入

这个问题的本质是React Native新架构构建流程中的一个环节缺失。代码生成是新架构的关键部分，它为每个原生模块创建：

• JNI接口代码
• C++类型定义
• 相应的CMake构建配置文件

当这个步骤未能自动执行时，后续的NDK构建就会因为缺少必要的配置文件而失败。

最佳实践建议

1. 逐步迁移：如果从旧架构迁移，建议逐步开启新架构特性，而不是一次性全部启用。

2. 版本一致性：确保React Native、Async Storage和其他第三方库的版本相互兼容。

3. 构建监控：在CI/CD流程中加入对新架构构建的专门检查步骤。

4. 文档参考：仔细阅读React Native官方文档中关于新架构迁移的指南。

总结

Async Storage在新架构下的构建问题通常源于代码生成步骤的执行问题。通过理解新架构的构建流程和代码生成机制，开发者可以更有效地解决这类问题。建议开发者在遇到类似问题时，首先尝试手动触发代码生成，然后系统地检查项目配置和依赖版本，确保整个工具链的兼容性。