从旧到新的跨越：个人项目迁移到 AGP 8.0+ & Gradle 8.0+ 的实战记录

引言

随着 Android 开发工具的不断发展，Android Gradle Plugin (AGP) 和 Gradle 的新版本带来了许多新功能和改进。然而，版本迁移往往伴随着一系列兼容性问题。本文将以我个人的项目为例，分享从 AGP 7.1.2 & Gradle 7.3.3 迁移到 AGP 8.0+ & Gradle 8.0+ 的全过程，包括遇到的挑战、解决方案及一些实用的建议。

迁移前准备

1. 评估项目现状

在开始迁移之前，首先需要评估项目的现状。检查项目中使用的依赖库、插件和构建脚本的兼容性。例如，如果项目中使用了大量老旧的 support 库，则需要考虑迁移到 AndroidX。

2. 备份项目

在进行任何重大更改之前，备份整个项目是一个好习惯。这可以确保在迁移过程中遇到问题时，能够恢复到原始状态。

迁移步骤

1. 更新 Gradle Wrapper

首先，需要更新 Gradle Wrapper 到与 AGP 8.0+ 兼容的版本。在项目的 gradle/wrapper/gradle-wrapper.properties 文件中，修改 distributionUrl 字段，例如：

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

2. 更新 Android Gradle Plugin

接下来，在项目的根 build.gradle 文件中更新 Android Gradle Plugin 的版本号。例如：

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:8.0.0'
    }
}

3. 使用 AGP Upgrade Assistant

Android Studio 内置的 AGP Upgrade Assistant 可以帮助自动化处理一些必要的变更。打开该工具，选择目标版本，并按照提示进行操作。如果某些步骤被阻止，需要根据提示修复警告项。

4. 解决 Java 版本问题

AGP 8.0 要求 JDK 17。因此，需要确保开发环境已安装 JDK 17，并在 Android Studio 中配置为默认 JDK。如果项目中使用的 Kotlin 版本与 JDK 17 不兼容，还需要更新 Kotlin 插件和 Kotlin 编译版本。

5. 适配 BuildConfig 变更

从 AGP 8.0 开始，默认情况下不再自动生成 BuildConfig 文件。如果项目中使用了 BuildConfig，需要在模块的 build.gradle 文件中启用它，或者在 gradle.properties 中设置 android.enableBuildConfigAsBytecode 为 true。

6. 处理 R8 和 ProGuard 规则

AGP 8.0 默认启用 R8 完整模式，这可能会导致一些旧有的 ProGuard 规则不再适用。根据 R8 的提示，更新或添加必要的规则到 proguard-rules.pro 文件中。

遇到的问题及解决方案

1. 编译错误

在迁移过程中，可能会遇到各种编译错误。例如，Java 版本不一致、Kotlin 编译失败等。通过更新 JDK、Kotlin 插件和编译版本，通常可以解决这些问题。

2. 依赖问题

如果项目中使用了第三方库，并且这些库尚未迁移到 AndroidX，可以使用 Jetifier 工具自动转换支持库引用。同时，注意检查并更新所有依赖库的版本。

3. 资源引用错误

在迁移后，可能会发现一些资源引用错误。这通常是由于资源 ID 发生变化或 R 类生成方式改变导致的。检查并更新资源引用，确保它们指向正确的资源。

实用建议

1. 逐步迁移：不要试图一次性解决所有问题。将迁移过程分解为多个小步骤，逐步解决每个问题。
2. 阅读官方文档：Android 官方文档是了解新版本功能和变更的最佳资源。在迁移过程中，经常查阅官方文档可以避免很多不必要的麻烦。
3. 社区支持：如果遇到难以解决的问题，可以寻求社区的帮助。在 Stack Overflow、GitHub 或 Android 开发者论坛上提问，通常可以得到快速的响应