Flutter Android Gradle 构建问题修复指南

问题概述

在 Flutter 项目中遇到 Android 构建错误，主要表现为 Gradle 插件版本不兼容、网络代理问题以及 Java 版本兼容性问题。

错误信息

初始错误

Plugin [id: 'com.android.application', version: '7.3.0', apply: false] was not found in any of the following sources:
- Gradle Core Plugins (plugin is not in 'org.gradle' namespace)
- Plugin Repositories (could not resolve plugin artifact 'com.android.application:com.android.application.gradle.plugin:7.3.0')

后续错误

1. Java 版本不兼容

   BUG! exception in phase 'semantic analysis' in source unit '_BuildScript_' Unsupported class file major version 65
   

2. JdkImage 转换错误

   Execution failed for JdkImageTransform: core-for-system-modules.jar
   Error while executing process jlink.exe
   

3. 网络代理问题

   Could not GET 'https://dl.google.com/dl/android/maven2/...'
   Received status code 405 from server: Method Not Allowed
   

4. 缺少 SDK 组件

   Failed to install the following SDK components:
   build-tools;33.0.1 Android SDK Build-Tools 33.0.1
   

根本原因分析

1. 版本兼容性问题

   • Android Gradle Plugin 7.3.0 在国内镜像源中找不到
   • Gradle 7.6.3 与 Java 21 不兼容（需要 Gradle 8.5+）
   • AGP 8.x 需要 Gradle 8.0+ 和 Java 17+

2. 网络环境问题

   • Google Maven 仓库在国内无法访问
   • 代理配置导致 HTTP 请求失败（405 错误）

3. Android SDK 版本问题

   • 新版 Android SDK (36) 与旧版 Gradle 不兼容
   • jlink 工具在处理 JDK 21 时出现问题

修复方案

1. 更新 android/settings.gradle

使用传统 Flutter 配置格式，添加国内镜像源：

// Copyright 2014 The Flutter Authors. All rights reserved.
pluginManagement {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/central' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

include ':app'

def localPropertiesFile = new File(rootProject.projectDir, "local.properties")
def properties = new Properties()

assert localPropertiesFile.exists()
localPropertiesFile.withReader("UTF-8") { reader -> properties.load(reader) }

def flutterSdkPath = properties.getProperty("flutter.sdk")
assert flutterSdkPath != null, "flutter.sdk not set in local.properties"
apply from: "$flutterSdkPath/packages/flutter_tools/gradle/app_plugin_loader.gradle"

关键点：

• pluginManagement 块必须放在文件最前面
• 使用阿里云镜像源加速依赖下载
• 使用传统 apply from 方式加载 Flutter 插件

2. 更新 android/build.gradle

配置 Android Gradle Plugin 和 Kotlin 版本：

buildscript {
    ext.kotlin_version = '1.9.22'
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/central' }
        google()
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:8.2.2'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/central' }
        google()
        mavenCentral()
    }
}

rootProject.buildDir = '../build'
subprojects {
    project.buildDir = "${rootProject.buildDir}/${project.name}"
}
subprojects {
    project.evaluationDependsOn(':app')
}

tasks.register("clean", Delete) {
    delete rootProject.buildDir
}

版本兼容性表：

Android Gradle Plugin	Gradle 版本	Kotlin 版本	Java 版本
8.2.2	8.0 - 8.5	1.9.22	17+

3. 更新 android/app/build.gradle

配置应用级构建设置：

plugins {
    id "com.android.application"
    id "kotlin-android"
}

def localProperties = new Properties()
def localPropertiesFile = rootProject.file('local.properties')
if (localPropertiesFile.exists()) {
    localPropertiesFile.withReader('UTF-8') { reader ->
        localProperties.load(reader)
    }
}

def flutterSdkPath = localProperties.getProperty('flutter.sdk')
assert flutterSdkPath != null, "flutter.sdk not set in local.properties"
apply from: "$flutterSdkPath/packages/flutter_tools/gradle/flutter.gradle"

def flutterVersionCode = localProperties.getProperty('flutter.versionCode')
if (flutterVersionCode == null) {
    flutterVersionCode = '1'
}

def flutterVersionName = localProperties.getProperty('flutter.versionName')
if (flutterVersionName == null) {
    flutterVersionName = '1.0'
}

android {
    namespace "com.example.flutter_application_1"
    compileSdk 34
    buildToolsVersion "34.0.0"
    ndkVersion flutter.ndkVersion

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    
    kotlinOptions {
        jvmTarget = '17'
    }
    
    packagingOptions {
        jniLibs {
            useLegacyPackaging = true
        }
    }

    sourceSets {
        main.java.srcDirs += 'src/main/kotlin'
    }

    defaultConfig {
        applicationId "com.example.flutter_application_1"
        minSdkVersion 21
        targetSdkVersion 34
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }

    buildTypes {
        release {
            signingConfig signingConfigs.debug
        }
    }
}

flutter {
    source '../..'
}

dependencies {}

关键配置说明：

• compileSdk 34 - 使用稳定的 SDK 版本，避免新版 SDK 的兼容性问题
• useLegacyPackaging = true - 解决 JNI 库打包问题
• jvmTarget = '17' - 与 compileOptions 保持一致

4. 更新 android/gradle/wrapper/gradle-wrapper.properties

配置 Gradle 版本：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.5-all.zip

注意： 使用腾讯云镜像加速 Gradle 下载。

5. 更新 android/gradle.properties

配置网络和构建选项：

org.gradle.jvmargs=-Xmx4G -XX:MaxMetaspaceSize=512m
android.useAndroidX=true
android.enableJetifier=true

# 禁用代理
systemProp.http.proxyHost=
systemProp.http.proxyPort=
systemProp.https.proxyHost=
systemProp.https.proxyPort=
systemProp.http.nonProxyHosts=*
systemProp.https.nonProxyHosts=*

# 禁用 Gradle 缓存
org.gradle.caching=false

版本兼容性参考

Gradle 与 Java 兼容性

Gradle 版本	Java 8	Java 11	Java 17	Java 21
7.6.3	✓	✓	✓	✗
8.0	✓	✓	✓	✗
8.5	✓	✓	✓	✓

AGP 与 Gradle 兼容性

AGP 版本	最低 Gradle	最高 Gradle
7.4.2	7.5	8.0
8.1.4	8.0	8.4
8.2.2	8.0	8.5

推荐配置组合

场景	AGP	Gradle	Kotlin	Java	SDK
稳定生产环境	8.2.2	8.5	1.9.22	17	34
开发环境 (Java 21)	8.2.2	8.5	1.9.22	21	34

常见错误排查

错误：Plugin not found

原因： 插件版本在仓库中不存在

解决：

1. 检查 settings.gradle 中的 pluginManagement.repositories 配置
2. 确认版本号是否正确
3. 尝试使用国内镜像源

错误：Unsupported class file major version

原因： Gradle 版本与 Java 版本不兼容

解决：

1. 查看 flutter doctor -v 中的 Java 版本
2. 升级 Gradle 到支持该 Java 版本的最低版本
3. 或者降级 Java 到当前 Gradle 支持的版本

错误：JdkImageTransform failed

原因： JDK 21 与 Android SDK 的兼容性问题

解决：

1. 使用稳定的 SDK 版本（如 34）
2. 添加 packagingOptions { jniLibs { useLegacyPackaging = true } }
3. 确保编译时 Java 版本一致性

错误：405 Method Not Allowed

原因： 代理配置问题或网络访问限制

解决：

1. 在 gradle.properties 中禁用代理
2. 使用国内镜像源
3. 检查网络连接状态

验证构建

清理缓存

cd android
.\gradlew.bat clean

刷新依赖

flutter clean
flutter pub get

构建调试 APK

flutter build apk --debug

构建发布 APK

flutter build apk --release

参考资源

• Gradle 版本兼容性
• Android Gradle Plugin 发布说明
• Flutter Android 构建文档
• 阿里云 Maven 仓库

快速修复脚本

如果遇到类似问题，可以按以下步骤快速修复：

1. 检查 flutter doctor -v 中的 Java 版本
2. 根据兼容性表选择合适的 Gradle 版本
3. 更新 gradle-wrapper.properties 中的 distributionUrl
4. 更新 build.gradle 中的 AGP 版本
5. 清理并重新构建

附录：完整配置文件

详见项目中的以下文件：

• android/settings.gradle
• android/build.gradle
• android/app/build.gradle
• android/gradle/wrapper/gradle-wrapper.properties
• android/gradle.properties