Android Gradle版本升级

发表于 | 分类于
Android Gradle版本升级

前言

在 Android 项目中升级 Gradle 版本，不是只改一个地方，而是三个地方必须配套升级，否则会出现兼容性问题。

版本对应关系

Gradle 版本 Android Gradle Plugin (AGP) Kotlin 插件版本 JDK版本 NDK CMake
8.4 8.3.0 1.9.20 17-21 25.1.8937393 3.22.1
8.2 8.2.0 1.9.10 17-20
8.0 8.1.0 1.8.22 17-19
7.5 7.4.2 1.8.10 11-19
7.4 7.3.1 1.7.20 11-18
6.1.1 4.0.2 1.3.72 8-13

JDK版本速记

8 用 17，7 用 11，6 用 8；2025 以后，17 是底线

个人建议：7以下的用JDK8，7及以上的都用17。

升级步骤

升级到 Gradle 8.4 + AGP 8.3.0 为例

推荐至少升级到 Gradle 7.5 + AGP 7.4.2 ，新版本的Android Studio对之前的Gradle会出现不兼容的问题。

修改Gradle版本

修改 gradle-wrapper.properties

路径：gradle/wrapper/gradle-wrapper.properties

1
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.4-all.zip

设置JDK版本

Settings => Build,Execution,Deployment => Build Tools => Gradle

image-20251111101733184

项目配置

修改AGP和Kotlin版本

修改项目根目录的 build.gradle（Project 级）

1
2
3
4
5
6
7
buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.3.0'
        // 如果用 Kotlin
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.20"
    }
}

⚠️ 注意：从 AGP 7.0 起，Google 推荐把插件声明移到 settings.gradle.kts 或 build.gradle 的 plugins {} 块。

推荐改成这样：

不改也能运行。

1
2
3
4
5
6
// 项目根目录 build.gradle
plugins {
    id 'com.android.application' version '8.3.0' apply false
    id 'com.android.library' version '8.3.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.20' apply false
}

镜像地址要换成https

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
buildscript {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/central' }
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        maven { url 'https://maven.aliyun.com/repository/apache-snapshots' }
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:8.3.0"
    }
}

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/central' }
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        maven { url 'https://maven.aliyun.com/repository/apache-snapshots' }
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

模块配置

AGP 8.0+ 要求在 android {} 块里加 namespace 'com.xxx.xxx'

1
2
3
android {
    namespace 'com.xxx.xxx'
}

NDK升级

如果项目使用了NDK，要下载对应版本的NDK和CMake

  • NDK版本是25.1.8937393

  • 对应需要的CMake版本3.22.1

可以通过 Tools => SDK Manager => SDK Tools 安装

修改Gradle配置（可选）

修改 gradle.properties（可选但推荐）

Gradle 8.x 默认启用 JDK 17，确保你本地和 CI 都装了 JDK 17。

1
2
3
org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
android.useAndroidX=true
android.enableJetifier=true

同步 & 清理

  1. 点击 Android Studio 提示的 “Sync Now”
  2. 执行一次 Clean & Rebuild
    1
    2
    ./gradlew clean
    ./gradlew assembleDebug

常见坑 & 解决方案

错误提示 解决方案
Minimum supported Gradle version is 8.4. Current version is 7.5. 你只改了 AGP，没改 gradle-wrapper.properties
Could not find com.android.tools.build:gradle:8.3.0. 检查是否用了代理 / 离线模式 / 仓库配置
Namespace not specified. AGP 8.0+ 强制在 android {} 块里加 namespace 'com.xxx.xxx'
compileSdkVersion is not specified. AGP 8.0+ 要求显式声明 compileSdk 34

一键回滚（建议先备份）

升级前，先 commit 一次代码，或者打 tag：

1
git tag before-gradle-upgrade

一旦编译失败，可以快速回退：

1
git reset --hard before-gradle-upgrade

总结

“三件套，一起改；先 wrapper，后 AGP；JDK 17 要配齐；namespace 别忘了。”

如果你现在项目版本比较低（比如 AGP 4.x），不要一口气升到 8.x，建议逐级升级（4→7→8），每次编译通过再往下走。