React Native CLI构建Android失败：SDK与Gradle版本不匹配

问题描述 #

使用React Native CLI构建Android应用时持续失败，核心原因是SDK版本与Gradle版本不匹配。构建过程中系统会自动选用未指定的Android Gradle Plugin（AGP）8.2.1及最新SDK版本，进而触发构建失败。

报错信息 #

Android gradle plugin: 8.2.1 Gradle: 8.0.1 Warning: SDK processing.
This version only understands SDK XML versions up to 3 but an SDK XML
file of version 4 was encountered. This can happen if you use versions
of Android Studio and the command-line tools that were released at
different times. WARNING: The specified Android SDK Build Tools
version (33.0.0) is ignored, as it is below the minimum supported
version (34.0.0) for Android Gradle Plugin 8.2.1. Android SDK Build
Tools 34.0.0 will be used.

当前配置文件 #

/android/build.gradle #

// Top-level build file where you can add configuration options common to all sub-projects/modules.

buildscript {
    ext {
        buildToolsVersion = "33.0.0"
        minSdkVersion = 21
        compileSdkVersion = 33
        targetSdkVersion = 33

        // We use NDK 23 which has both M1 support and is the side-by-side NDK version from AGP.
        ndkVersion = "23.1.7779620"
    }
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle")
        classpath("com.facebook.react:react-native-gradle-plugin")
    }
}

gradle-wrapper.properties #

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0.1-all.zip
networkTimeout=10000
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

解决方案 #

1. 匹配AGP与Gradle版本 #

AGP 8.2.1要求Gradle版本最低为8.5，当前使用的Gradle 8.0.1不满足要求，需修改gradle-wrapper.properties中的distributionUrl：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-all.zip

2. 升级SDK相关版本 #

AGP 8.2.1要求最低Build Tools版本为34.0.0，同时建议compileSdkVersion和targetSdkVersion使用对应兼容的SDK版本，修改/android/build.gradle中的ext块：

ext {
    buildToolsVersion = "34.0.0"
    minSdkVersion = 21 // 可根据需求保留或调整
    compileSdkVersion = 34
    targetSdkVersion = 34

    ndkVersion = "23.1.7779620" // NDK 23与AGP 8.x兼容，无需修改
}

3. 指定AGP固定版本 #

避免系统自动选择最新AGP版本，在/android/build.gradle的dependencies中明确指定AGP版本：

dependencies {
    classpath("com.android.tools.build:gradle:8.2.1")
    classpath("com.facebook.react:react-native-gradle-plugin")
}

4. 解决SDK XML版本不兼容问题 #

报错中提到的SDK XML版本4问题，是由于Android Studio与命令行工具版本不一致导致：

• 打开Android Studio的SDK Manager，确保Command-line Tools更新到与Android Studio版本匹配的最新稳定版
• 同时确保Android Studio本身是最新稳定版

5. 验证SDK安装 #

在SDK Manager中确认已安装：

• Android SDK 34
• Android SDK Build Tools 34.0.0

完成以上修改后，执行./gradlew clean清理构建缓存，再重新尝试构建即可。

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