Flutter构建APK时AGP版本与compileSdk不匹配的解决方法

问题描述

在Flutter项目中构建APK发布文件时，常遇到如下编译错误：

[!] Using compileSdk 35 requires Android Gradle Plugin (AGP) 8.1.0 or higher
│  Please upgrade to a newer AGP version. 
│  The version of AGP that your project uses is likely defined in:
│  android/settings.gradle,
│  in the 'plugins' closure.
│ 
│  Alternatively, if you have a strong reason to avoid upgrading AGP, you can
│  temporarily lower the compileSdk version

核心问题：当你在 android/app/build.gradle 中设置 compileSdkVersion = 35 时，必须配合使用 Android Gradle Plugin（AGP）8.1.0 或更高版本。如果当前AGP版本过低，就会触发此错误。

关键提醒

错误信息明确指出了两个关键文件需要检查：

1. android/settings.gradle → AGP版本声明位置
2. android/build.gradle → 老项目可能在此定义版本

推荐解决方案

1. 升级AGP和Gradle版本

这是最可靠和推荐的修复方案：

步骤1：修改 android/settings.gradle 文件

plugins {
    id("com.android.application") version "8.9.0" apply false
    id("com.android.library") version "8.9.0" apply false
    id("org.jetbrains.kotlin.android") version "2.1.10" apply false
}

AGP与Gradle对应关系

参考官方兼容性文档，AGP版本和Gradle版本需匹配：

AGP版本	Gradle版本
8.1.0	8.0+
8.9.0	8.11.1

步骤2：升级Gradle Wrapper 修改 android/gradle/wrapper/gradle-wrapper.properties：

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

步骤3：清理缓存并重建 终端执行命令：

flutter clean
flutter pub get
cd android && ./gradlew clean

2. 解决Java/Kotlin版本冲突

升级AGP后可能出现JDK版本不兼容，需配置目标版本：

修改 android/app/build.gradle：

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    
    kotlinOptions {
        jvmTarget = "17" // 与Java版本保持一致
    }
}

常见错误

'compileDebugJavaWithJavac' task failed
Kotlin编译器与Java目标版本不一致

3. 更新NDK（可选步骤）

若出现NDK相关错误：

1. 打开 Android Studio > SDK Manager > SDK Tools
2. 更新 NDK (Side by side) 到最新版本
3. 在 android/app/build.gradle 中指定版本：

android {
    ndkVersion = "27.2.12479018" // 替换为安装的版本号
}

替代解决方案

方案A：降低 compileSdk 版本（临时急救）

仅当无法立即升级AGP时使用，修改 android/app/build.gradle：

android {
    compileSdkVersion 33  // 降级到旧版本，如33
}

不推荐长期使用

此方法会导致无法使用Android API的新功能，应尽快升级AGP

方案B：重置Android目录（极端情况）

删除整个android目录然后重建：

rm -rf android 
flutter create .

⚠️ 注意：这会重置所有Android配置，需重新配置签名等设置

验证与后续处理

构建APK和App Bundle的命令：

flutter build apk
flutter build appbundle

若仍报错，尝试清理缓存：

flutter clean
cd android && ./gradlew cleanBuildCache

::: success 完整升级示例

# 1. 修改 settings.gradle 和 gradle-wrapper.properties
# 2. 清理缓存
flutter clean && flutter pub get
# 3. 重建Android项目
cd android && ./gradlew clean
# 4. 构建发布文件
flutter build apk --release

:::