React Native Async Storage 在 New Architecture 下的构建问题解析

问题背景

在使用 React Native 的 New Architecture 模式构建项目时，开发者可能会遇到一个特定的构建错误，提示找不到 Async Storage 模块的 CMakeLists.txt 文件。这个问题主要出现在 Android 平台的构建过程中，特别是在启用了新架构(IS_NEW_ARCHITECTURE_ENABLED = TRUE)的情况下。

错误表现

构建过程中会出现类似以下的错误信息：

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

问题原因

这个问题的根本原因在于 New Architecture 的代码生成机制。当启用新架构时，React Native 会使用代码生成(Codegen)来自动创建必要的本地接口文件，包括 CMakeLists.txt。但在某些情况下，这个自动生成过程可能没有正确执行，导致构建系统找不到预期的文件。

解决方案

临时解决方案

开发者可以手动执行以下命令来生成缺失的文件：

./gradlew generateCodegenArtifactsFromSchema

这个命令会强制触发代码生成过程，创建所有必要的文件，包括缺失的 CMakeLists.txt。

长期解决方案

1. 检查依赖版本兼容性：确保使用的 React Native 版本与 Async Storage 版本兼容。较新的 React Native 版本(如 0.73+)通常需要对应版本的 Async Storage。

2. 清理构建缓存：在尝试重新构建前，执行完整的清理操作：

./gradlew clean
rm -rf android/.cxx

3. 验证项目配置：确保项目正确配置了 New Architecture 相关的设置，包括：
   • gradle.properties 中正确设置了 newArchEnabled=true
   • build.gradle 中正确配置了 React Native Gradle 插件

技术深入

New Architecture 下的构建过程与传统架构有显著不同。它依赖于代码生成来创建 JNI 接口和本地模块绑定。Async Storage 作为原生模块，需要正确参与这个过程。

当构建系统找不到 CMakeLists.txt 时，通常意味着：

1. 代码生成步骤没有自动执行
2. 生成的文件被错误地清理掉了
3. 文件生成路径与构建系统预期不匹配

最佳实践建议

1. 构建顺序：在启用 New Architecture 的项目中，建议先执行代码生成，再进行完整构建。

2. 环境一致性：确保开发团队的 JDK、Gradle 和 Android Studio 版本一致，避免环境差异导致的问题。

3. 版本锁定：对于关键依赖如 React Native 和 Async Storage，使用精确版本号而非范围版本，确保构建一致性。

4. 构建脚本增强：考虑在项目的构建脚本中添加代码生成步骤作为前置条件，自动化解决此问题。

总结

React Native New Architecture 带来了性能优势，但也引入了更复杂的构建流程。Async Storage 作为常用存储解决方案，在新架构下的构建问题通常可以通过正确触发代码生成步骤来解决。理解 New Architecture 的构建机制有助于开发者更高效地解决类似问题。