React Native项目Gradle同步失败：native_modules.gradle文件缺失排查

问题描述 #

React Native项目构建时，settings.gradle文件触发同步失败，错误信息如下：

Settings file 'C:\Users\andre\WatchList\android\settings.gradle' line: 2

A problem occurred evaluating settings 'WatchList'.
> Could not read script 'C:\Users\andre\WatchList\node_modules\@react-native-community\cli-platform-android\native_modules.gradle' as it does not exist.

疑问 #

• 为何重新安装依赖后native_modules.gradle文件仍缺失？
• 正确生成或解决该缺失文件问题的步骤是什么？

已尝试操作 #

• 重新安装依赖：执行npm install
• 检查node_modules目录：确认@react-native-community/cli-platform-android存在，但缺少native_modules.gradle文件
• 清理缓存并重装：执行npm cache clean --force，删除node_modules文件夹后重新执行npm install
• 验证settings.gradle内容：

  rootProject.name = 'WatchList'
  apply from: file("../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesSettingsGradle(settings)
  include ':app'
  includeBuild('../node_modules/@react-native/gradle-plugin')
  

环境信息 #

React Native v0.76.3、Node.js v20.14.0、npm 10.8.2、Windows 11

问题解答 #

1. 为何重装依赖后文件仍缺失？ #

核心原因是React Native 0.76+版本已废弃@react-native-community/cli-platform-android中的native_modules.gradle脚本：

• 新版本RN将CLI工具集成到核心模块@react-native/gradle-plugin中，旧的cli-platform-android模块结构已变更，不再包含该文件
• 项目的package-lock.json可能锁定了旧依赖逻辑，导致重装后模块结构仍不符合新版本要求
• 网络波动可能导致依赖包下载不完整，出现文件缺失

2. 解决步骤 #

步骤1：修正settings.gradle配置

直接删除旧的CLI脚本引用，保留RN 0.76.x标准配置：

rootProject.name = 'WatchList'
include ':app'
includeBuild('../node_modules/@react-native/gradle-plugin')

步骤2：彻底清理并重装依赖

1. 删除项目根目录下的node_modules文件夹
2. 删除package-lock.json文件（避免锁定旧依赖版本）
3. 执行npm install重新安装依赖
4. 进入android目录，执行gradlew clean清理Android构建缓存

步骤3：移除不必要的CLI依赖

检查package.json，如果有单独声明@react-native-community/cli或@react-native-community/cli-platform-android的条目，直接删除——RN 0.76+会自动管理CLI相关依赖，无需手动指定。

步骤4：验证Android构建配置

确保android/build.gradle中的关键配置符合RN 0.76.x要求，核心部分示例：

buildscript {
    ext {
        buildToolsVersion = "34.0.0"
        minSdkVersion = 21
        compileSdkVersion = 34
        targetSdkVersion = 34
        ndkVersion = "25.1.8937393"
    }
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:8.2.0")
        classpath("com.facebook.react:react-native-gradle-plugin")
    }
}

完成以上步骤后，重新同步Gradle即可解决问题。

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