Android Gradle版本升级至7.5

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

前言

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

注意

Gradle 升级除了相关的依赖要升级，项目的依赖可能也要升级，甚至可能没有兼容的依赖，所以升级要慎重。

升级前提

如果项目中还使用了ButterKnife，就不要升级到Gradle 7.5。

ButterKnife 本质上不直接兼容 Gradle 7.5，核心原因是 ButterKnife 已停止维护，且其依赖的注解处理器（APT）机制、插件架构与 Gradle 7.x（含 7.5）+ AGP 7.x 的新特性冲突。AGP 7.x 调整了注解处理器（APT）的配置方式（废弃 android-apt 插件，统一使用 Gradle 原生 annotationProcessor 或 kapt），ButterKnife 依赖的旧版 APT 逻辑无法适配。

版本对应关系

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。

一键回滚

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

1
git tag before-gradle-upgrade

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

1
git reset --hard before-gradle-upgrade

升级步骤

推荐至少升级到 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-7.5-all.zip

设置JDK版本

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

image-20251111101733184

gradle.properties

JDK的参数去掉-XX:MaxPermSize=4096m

项目配置

修改AGP和Kotlin版本

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

1
2
3
4
5
6
7
buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:7.4.2'
        // 如果用 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 '7.4.2' apply false
    id 'com.android.library' version '7.4.2' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.20' apply false
}

镜像更换HTTPS

镜像地址要换成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:7.4.2"
    }
}

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()
    }
}

镜像兼容HTTP

只有http的，添加allowInsecureProtocol = true

1
2
3
4
maven {
    allowInsecureProtocol = true
    url 'http://download.flutter.io'
}

模块配置

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

同步 & 清理

点击 Android Studio 提示的 “Sync Now”

执行一次 Clean & Rebuild

1
2
./gradlew clean
./gradlew assembleDebug

总结

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

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