Android Studio AGP 4升级到AGP 7

发表于 更新于 分类于
Android Studio AGP 4升级到AGP 7

前言

之前Android Studio在运行项目的时候，能正常运行，但是配置文件都报红，这是因为和Android Studio版本不兼容。

升级新版本的Android Studio Panda 2 | 2025.3.2 就可以了，但是一升级又导致新的问题，旧项目又不支持了。

提示让升级AGP

The project is using an incompatible version (AGP 4.0.1) of the Android Gradle plugin. Minimum supported version is AGP 7.0.0.

这里就记录下AGP升级过程。

AGP 4.0.1 已被彻底淘汰，自 Narwhal Feature Drop (2025.1.2) 起，Android Studio 不再支持 AGP < 4.0，但实际从 2023 年起主流 IDE 已要求 AGP ≥ 7.0。

项目升级到 AGP 7.0.0 或更高版本，并同步调整配套的 Gradle 版本 和 JDK 版本。

AGP 7.4.2 是一个稳定且广泛兼容的版本，支持 JDK 11/17，Gradle 7.5+。

注意

AGP 不要直接直接升级到 AGP8。

AGP 不要直接直接升级到 AGP8。

AGP 不要直接直接升级到 AGP8。

我这尝试升级AGP8出现除了环境配置都要修改外，很多代码都要修改，太多了，最后还是使用AGP7.4.2了。

对应的版本（以本地实际落地为准）

  • AGP 7.4.2
  • Gradle 7.6.3
  • Kotlin 1.7.22（languageVersion / apiVersion 仍用 1.6 兼容旧代码）
  • JDK 17.0.4
  • compileSdk 33 / buildTools 30.0.3 / minSdk 21 / targetSdk 29
  • R8 8.2.47（覆盖 AGP 自带版本，修复 Anko dexing）
  • CameraX 1.2.0 / WorkManager 2.7.1 / Anko 0.10.8

解决方案

你需要将项目升级到 AGP 7.0.0 或更高版本，并同步调整配套的 Gradle 版本 和 JDK 版本。

注意

AGP 4.0.1 已被彻底淘汰，自 Narwhal Feature Drop (2025.1.2) 起，Android Studio 不再支持 AGP < 4.0，但实际从 2023 年起主流 IDE 已要求 AGP ≥ 7.0。

升级 Gradle 和 AGP

修改Gradle版本

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

本地实际使用：

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

阿里云镜像也可：

1
distributionUrl=https\://mirrors.aliyun.com/gradle/distributions/v7.6.3/gradle-7.6.3-all.zip

说明：AGP 7.4.2 最低要求 Gradle 7.5+；本地因构建时出现 Gradle 自身的 java.lang.StackOverflowError（堆栈在 FinalizerGroup.isCanCancel），最终使用 7.6.3，并在 gradle.properties 中加大线程栈：

1
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m -Xss4m -Dfile.encoding=UTF-8

修改AGP版本

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

1
2
3
4
5
6
// build.gradle (Project)
buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:7.4.2'
    }
}

修改Kotlin版本

1
2
3
buildscript {
    ext.kotlin_version = '1.7.22'
}

清理已废弃的 classpath / 插件

AGP 4 时代常见、AGP 7 下应删除的插件：

1
2
3
4
5
// 根 build.gradle 的 classpath 中删除：
// classpath 'me.tatarka:gradle-retrolambda:...'
// classpath 'com.github.dcendents:android-maven-gradle-plugin:...'
// classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:...'
// classpath 'com.github.dcendents:android-maven-plugin:...'

模块里若有：

1
2
apply plugin: 'com.github.dcendents.android-maven'
apply plugin: 'com.jfrog.bintray'

一并删除。Bintray 已关停，本地库模块一般也不再需要这些发布插件。

添加命名空间

报错

Namespace not specified. Specify a namespace in the module’s build file.

每一个 Android 模块都要添加对应的命名空间，值取自该模块 AndroidManifest.xml 的 package：

1
2
3
android {
    namespace 'com.xhly.easystud'
}

注意：

Manifest 里的 package 属性在 AGP 7 中已废弃，但可暂时保留；真正生效的是 build.gradle 里的 namespace。

所有 library / application 模块都要加，漏一个就会同步失败。

设置JDK版本

AGP 7.4 推荐使用 JDK 11/17（AGP 8.0+ 强制 JDK 17）。本地升级到 AGP 7.4.2 后使用 JDK 17.0.4。

设置中配置

image-20250924100237470

也可在项目 local.properties 指定（仅本机，勿提交仓库）：

1
org.gradle.java.home=D\:\\Tools\\jdk-17.0.4

在模块级 build.gradle 中显式指定：

1
2
3
4
5
6
7
8
9
10
android {
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_1_8
    }
    compileOptions {
        coreLibraryDesugaringEnabled true
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

注意

构建用 JDK 17 + 工程编译目标仍是 1.8 是常见且正常的组合，不用改 JavaVersion.VERSION_1_8为17。

提升 compileSdk

升级 AGP 后，若依赖了较新的 AndroidX（本地为 CameraX 1.2.0、WorkManager 2.7.1），compileSdk 30 会报：

The minCompileSdk (31/33) specified in a dependency’s AAR metadata is greater than this module’s compileSdkVersion

本地实际配置：

1
2
3
4
5
// config.gradle
compileSdkVersion 33
buildToolsVersion "30.0.3"
minSdkVersion 21
targetSdkVersion 29

gradle.properties：

1
2
android.suppressUnsupportedCompileSdk=33
android.nonTransitiveRClass=false

注意：

本地只升了 compileSdk 到 33，targetSdk 仍保持 29，降低 Manifest / 行为变更风险。

镜像地址

Android 下载依赖报错的原因是 Gradle 7.0+ 默认不再支持不安全的 HTTP 协议仓库。

仓库配置应写在 settings.gradle（不是根 build.gradle）。

Groovy

settings.gradle

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
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/public' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    // 有私有仓 / 模块内仍声明仓库时，用 PREFER_SETTINGS 更稳妥
    // 纯净项目可用 FAIL_ON_PROJECT_REPOS
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/central' }
        maven { url 'https://maven.aliyun.com/repository/public' }
        google()
        mavenCentral()
        maven { url "https://jitpack.io" }
        // 特殊依赖仓库按需保留，例如 mupdf：
        // maven { url 'https://maven.ghostscript.com/' }
    }
}

根 build.gradle 的 allprojects { repositories { ... } } 可逐步删掉，避免和 settings.gradle 重复。

KTS

settings.gradle.kts

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
27
28
pluginManagement {
    repositories {
        maven("https://maven.aliyun.com/repository/central")
        maven("https://maven.aliyun.com/repository/public")
        maven ("https://maven.aliyun.com/repository/gradle-plugin")
        maven ("https://maven.aliyun.com/repository/apache-snapshots")
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven("https://maven.aliyun.com/repository/central");
        maven("https://maven.aliyun.com/repository/public");
        maven("https://maven.aliyun.com/repository/gradle-plugin")
        maven("https://maven.aliyun.com/repository/apache-snapshots")
        google()
        mavenCentral()
    }
}

支持Flutter

1
2
3
4
maven("http://download.flutter.io") {
    // 信任http协议
    isAllowInsecureProtocol = true
}

或者华为的镜像地址

1
maven("https://mirrors.huaweicloud.com/repository/maven/")

AGP 7 废弃 API 替换

模块 build.gradle 里这些写法需要改：

lintOptions → lint

1
2
3
4
5
6
7
8
9
// 旧
lintOptions {
    abortOnError false
}

// 新
lint {
    abortOnError false
}

packagingOptions

1
2
3
4
5
6
7
8
9
10
11
// 旧
packagingOptions {
    exclude 'META-INF/rxjava.properties'
}

// 新
packagingOptions {
    resources {
        excludes += ['META-INF/rxjava.properties']
    }
}

aaptOptions

aaptOptions.cruncherEnabled / useNewCruncher 在 AGP 7 已无意义，直接删除。

ndk abiFilters

armeabi 已移除，只保留仍支持的 ABI：

1
2
3
4
ndk {
    abiFilters "armeabi-v7a"
    // 需要再加 "arm64-v8a"
}

APK 重命名

1
2
3
4
5
6
// 旧：android.applicationVariants.all { ... }
applicationVariants.all { variant ->
    variant.outputs.all {
        outputFileName = "App-${variant.name}-${variant.versionName}.apk"
    }
}

Support Library 改为 AndroidX

子模块若仍依赖：

1
implementation 'com.android.support:appcompat-v7:27.1.1'

在已开启 android.useAndroidX=true + android.enableJetifier=true 的前提下，建议直接改成：

1
implementation 'androidx.appcompat:appcompat:1.3.1'

testInstrumentationRunner 也从 android.support.test.runner.AndroidJUnitRunner 改为 androidx.test.runner.AndroidJUnitRunner。

常见问题

插件不支持

Plugin [id: ‘maven’] was not found in any of the following sources

改为

1
2
3
plugins {
    id 'maven-publish'
}

Could not set unknown property ‘classifier’ for task ‘:lib_agora:androidSourcesJar’ of type org.gradle.api.tasks.bundling.Jar

把原来的

1
2
3
4
task androidSourcesJar(type: Jar) {
    classifier = 'sources' 
    from android.sourceSets.main.java.srcDirs
}

改为

1
2
3
4
task androidSourcesJar(type: Jar) {
    archiveClassifier = 'sources'
    from android.sourceSets.main.java.srcDirs
}

Manifest合并问题

处理 Manifest 合并问题（Android 12+）

如果你的 targetSdk >= 31，需为所有 <activity>、<service>、<receiver> 显式添加 android:exported 属性：

1
2
3
4
5
6
7
8
<activity
    android:name=".MainActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

❗否则会报错：Manifest merger failed : android:exported needs to be explicitly specified

Anko 导致 D8 / dexing 失败

报错类似：

ERROR:D8: No VersionRequirement with the given id in the table
Failed to transform anko-coroutines-0.10.8 / anko-sdk27-coroutines-0.10.8 …

Anko 已停止维护，其 coroutines 子模块与 AGP 7.4 自带 D8 不兼容。处理方式：

1. 排除 Anko coroutines 子模块

1
2
3
4
5
6
implementation("org.jetbrains.anko:anko:0.10.8") {
    exclude group: 'org.jetbrains.anko', module: 'anko-coroutines'
    exclude group: 'org.jetbrains.anko', module: 'anko-sdk27-coroutines'
    exclude group: 'org.jetbrains.anko', module: 'anko-appcompat-v7-coroutines'
    exclude group: 'org.jetbrains.anko', module: 'anko-support-v4-coroutines'
}

若代码用了 org.jetbrains.anko.sdk27.coroutines.textChangedListener，改为 AndroidX / 原生 TextWatcher。

2. 覆盖 AGP 自带 R8（可选，但很有效）

根 build.gradle：

1
2
3
4
5
6
7
8
9
10
buildscript {
    repositories {
        maven { url 'https://storage.googleapis.com/r8-releases/raw' }
        // ...其它仓库
    }
    dependencies {
        classpath 'com.android.tools:r8:8.2.47'
        classpath 'com.android.tools.build:gradle:7.4.2'
    }
}

Kotlin 1.7：when 必须穷尽

升级 Kotlin 到 1.7 后，枚举 when 未写全分支会从 warning 变成 error：

‘when’ expression must be exhaustive, add necessary ‘XXX’ branches or ‘else’ branch

两种处理：

方案 A（推荐长期）： 给每个 when 补 else 或补全枚举分支。

方案 B（快速兼容旧代码）： 暂时把语言级别降回 1.6：

1
2
3
4
5
6
7
android {
    kotlinOptions {
        jvmTarget = '1.8'
        languageVersion = "1.6"
        apiVersion = "1.6"
    }
}

compileSdk 33：MediaMetadataRetriever.release()

compileSdk 33 后，MediaMetadataRetriever.release() 声明会抛 IOException，旧代码直接调用会编译失败：

1
2
3
4
5
6
7
} finally {
    try {
        retriever.release();
    } catch (Exception e) {
        e.printStackTrace();
    }
}

不支持 butterknife

butterknife 的改为 viewBinding

这个改动就比较大了

kotlin-android-extensions

kotlin-android-extensions（kotlinx.android.synthetic）在 Kotlin 1.8+ 已移除。

升级到 AGP 7.4 + Kotlin 1.7.22 时，暂时还能编译，但是IDE工具上是报错的，但后续升 Kotlin / AGP 8 前必须迁到 View Binding。

量大时可先保留插件，把迁移单独排期，不要和 AGP 升级绑死。

清理并重试

Build > Clean Project

清空缓存

File > Invalidate Caches / Restart

同步依赖

File > Sync Project with Gradle Files

如果构建卡可以使用这个测试

1
gradlew.bat :app:assembleDebug --no-daemon

命令行验证时记得切到本地 JDK 17.0.4：

1
2
set JAVA_HOME=D:\Tools\jdk-17.0.4
gradlew.bat :app:assembleXhlyDebug --no-daemon

备选方案

降级 Android Studio（不推荐）

如果你无法修改老项目（如第三方闭源项目），可考虑：

  • 安装旧版 Android Studio（如 Arctic Fox 2020.3.1），它支持 AGP 4.0.1。
  • 但会失去新功能、安全更新和调试支持。

注意：

更好的做法是 升级项目，而非降级工具链。

以下情况不建议升级：

  • 项目比较庞大，并且大量使用了Butterknife，这种情况迁移难度太大。我这里15个子模块，在AI的帮助下迁移了2天。
  • 项目三方依赖使用了Butterknife，这种情况得把三方的下载下来，手动改。

总结

本地实际落地版本：

组件 原版本 升级到（本地实际）
AGP 4.1.0 7.4.2
Gradle 6.7.1 7.6.3
JDK 8 17.0.4
Kotlin 1.6.21 1.7.22（languageVersion/apiVersion=1.6）
compileSdk 30 33
buildTools 30.0.3 30.0.3（未改）
minSdk 21 21（未改）
targetSdk 29 29（暂未升）
R8 AGP 自带 8.2.47
CameraX 1.0.x 1.2.0
WorkManager 2.5.0 2.7.1
Anko 0.10.8 0.10.8（排除 coroutines 子模块）
Android Studio 任意新版 保持最新，但需匹配 AGP

升级时除版本号外，还要同步处理：

  1. 全模块 namespace
  2. 删除 bintray / android-maven / retrolambda
  3. lintOptions / packagingOptions / aaptOptions / armeabi 等废弃配置
  4. Support Library → AndroidX
  5. Anko coroutines 排除 + 覆盖 R8 8.2.47
  6. Kotlin 穷尽 when / MediaMetadataRetriever.release() 等编译问题

完成上述修改后，项目应能正常同步和构建。