Android Studio 构建系统以 Gradle 为基础，并且 Android Gradle 插件添加了几项专用于构建 Android 应用的功能。虽然 Android Gradle 插件 (AGP) 通常与 Android Studio 的更新步调保持一致，但该插件（以及 Gradle 系统的其余部分）可独立于 Android Studio 运行并单独更新。

1. 更新 Android Gradle 插件

在更新 Android Studio 时，可能会收到将 Android Gradle 插件自动更新为最新可用版本的提示。可以选择接受该更新，也可以根据项目的构建要求手动指定版本。

可以在 Android Studio 的 File > Project Structure > Project 菜单中指定插件版本，也可以在顶级 build.gradle 文件中指定。该插件版本适用于在相应 Android Studio 项目中构建的所有模块。以下示例将 build.gradle 文件中的插件设置为版本 8.4.0：

plugins {
    id 'com.android.application' version '8.4.0' apply false
    id 'com.android.library' version '8.4.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.23' apply false
}

如果指定的插件版本尚未下载，则 Gradle 会在下次构建项目时进行下载；或者也可以在 Android Studio 菜单栏中依次点击 File > Sync Project with Gradle Files 进行下载。

2. 更新 Gradle

在更新 Android Studio 时，可能会收到一并将 Gradle 更新为最新可用版本的提示。可以选择接受该更新，也可以根据项目的构建要求手动指定版本。

下表列出了各个 Android Gradle 插件版本所需的 Gradle 版本。为了获得最佳性能，应使用 Gradle 和插件这两者的最新版本。

可以在 Android Studio 的 File > Project Structure > Project 菜单中指定 Gradle 版本，也可以使用命令行更新 Gradle 版本。首选方法是使用 Gradle Wrapper命令行工具，该工具可更新 gradlew 脚本。以下示例使用 Gradle 封装容器将 Gradle 版本设置为 8.4。 请注意，您需要运行此命令两次来升级 Gradle 和 Gradle 封装容器本身（如需了解详情，请参阅升级 Gradle Wrapper）。

gradle wrapper --gradle-version 8.4

不过，此操作在某些情况下可能会失败，例如刚刚更新了 AGP，导致其不再与当前 Gradle 版本兼容。在这种情况下，需要修改 gradle/wrapper/gradle-wrapper.properties 文件中的 Gradle 分发引用。以下示例在 gradle-wrapper.properties 文件中将 Gradle 的版本设置为 8.4。

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.4-bin.zip
...

3. Android Gradle 插件和 Android Studio 兼容性

Android Studio 构建系统以 Gradle 为基础，并且 Android Gradle 插件 (AGP) 添加了几项专用于构建 Android 应用的功能。下表列出了各个 Android Studio 版本所需的 AGP 版本：

4. Android API 级别要求的最低工具版本

Android Studio 和 AGP 的最低版本支持特定的 API 级别。使用低于项目要求的 Android Studio 或 AGP 版本 targetSdk 可能 compileSdk 会导致意外问题。建议使用最新预览版的 Android Studio 和 AGP 来处理面向 Android 操作系统预览版的项目。

Android Studio 和 AGP 的最低版本如下：

5. Android Gradle 插件升级到 7.0

Android Gradle 插件升级到 7.0，需要开发者需要将 JDK 升级到 11，同时升级 Android Studio 到 Chipmunk 或更高版本。

5.1 升级 Gradle 插件版本

Gradle 插件版本是 Gradle 与 Android 构建系统之间的接口。因此，在升级 Gradle 之前，需要先升级 Gradle 插件版本。在项目根目录下的 build.gradle 文件中修改 Gradle 插件的版本，有以下 2 种方式：

• 将 classpath 中的 Gradle 插件版本改为 7.4.2：

  buildscript {
    repositories {
        google()        // Google's Maven repository
        mavenCentral()  // Maven Central repository
    }
  
    dependencies {
        // Add the dependency for the Android Gradle plugin
        classpath 'com.android.tools.build:gradle:7.4.2'
    }
  }
  

• 将 com.android.application 和 com.android.library 版本改为 7.4.2：

  plugins {
    id 'com.android.application' version '7.4.2' apply false
    id 'com.android.library' version '7.4.2' apply false
  }
  

5.2 升级 Gradle 版本

接下来，需要升级 Gradle wrapper 版本。在项目根目录下的 /gradle/wrapper/gradle-wrapper.properties 文件中，将 distributionUrl 改为 7.5，如下所示：

distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-bin.zip

5.3 设置构建 JDK 版本

从 Android Studio Arctic Fox 开始，Android Studio IDE 与 JDK 11 捆绑在一起。如果 Android Studio 配置为使用嵌入式 JDK，新项目将使用最新稳定版本的 Android Gradle 插件和 JDK 17。但是，现有项目可能会中断，可能需要手动将 JDK 设置为兼容版本。

可以在 Android Studio 的 File > Settings > Build, Execution, Deployment > Build Tools > Gradle 菜单中指定 Gradle JDK 版本：

从现在开始，可以在应用程序的项目中编译最高可达 Java 11 的源代码，从而能够使用较新的语言功能，例如私有接口方法、匿名类的菱形运算符以及 lambda 参数的局部变量语法。要启用此功能，请在 build.gradle 文件中设置 compileOptions 所需的 Java 版本并设置 compileSdkVersion 为 30 或更高版本：

android {
    compileSdkVersion 30
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_11.toString()
    }
}

5.4 构建配置变更

如果使用的是 AGP 7.0.0 或更高版本，应用的 build.gradle 文件中的构建配置有部分变更：

android {
    compileSdk 33

    defaultConfig {
        minSdk 21
        targetSdk 33
    }
}

如果使用的是 AGP 4.2.0 或更低版本，应用的 build.gradle 文件配置如下：

android {
    compileSdkVersion 33

    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }
}

5.5 依赖配置变更

在 AGP 7.0 中，以下配置（或依赖范围）已被删除：

• compile：被替换为 api 或 implementation。
• provided：被替换为 compileOnly。
• apk：被替换为 runtimeOnly。
• publish：被替换为 runtimeOnly。

在大多数情况下，AGP 升级助手会自动将您的项目迁移到新配置。

6. Android Gradle 插件升级到 8.0

Android Gradle 插件升级到 8.0，需要开发者需要将 JDK 升级到 17，同时升级 Android Studio 到 Flamingo 或更高版本。

6.1 升级 Gradle 插件版本

Gradle 插件版本是 Gradle 与 Android 构建系统之间的接口。因此，在升级 Gradle 之前，需要先升级 Gradle 插件版本。在项目根目录下的 build.gradle 文件中修改 Gradle 插件的版本，有以下 2 种方式：

• 将 classpath 中的 Gradle 插件版本改为 8.0.2：

  buildscript {
    repositories {
        google()        // Google's Maven repository
        mavenCentral()  // Maven Central repository
    }
  
    dependencies {
        // Add the dependency for the Android Gradle plugin
        classpath 'com.android.tools.build:gradle:8.0.2'
    }
  }
  

• 将 com.android.application 和 com.android.library 版本改为 8.0.0：

  plugins {
    id 'com.android.application' version '8.0.2' apply false
    id 'com.android.library' version '8.0.2' apply false
  }
  

6.2 升级 Gradle 版本

接下来，需要升级 Gradle wrapper 版本。在项目根目录下的 /gradle/wrapper/gradle-wrapper.properties 文件中，将 distributionUrl 改为 8.0.2，如下所示：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.0.2-bin.zip

6.3 设置构建 JDK 版本

从 Android Studio Flamingo 开始，Android Studio IDE 与 JDK 17 捆绑在一起。如果 Android Studio 配置为使用嵌入式 JDK，新项目将使用最新稳定版本的 Android Gradle 插件和 JDK 17。但是，现有项目可能会中断，可能需要手动将 JDK 设置为兼容版本。

可以在 Android Studio 的 File > Settings > Build, Execution, Deployment > Build Tools > Gradle 菜单中指定 Gradle JDK 版本：

[!TIP|labelVisibility:hidden|iconVisibility:hidden] JDK 17 仅用于构建，Android 工程还是只能用 Java 11。

6.4 设置命名空间

每个 Android 模块都有一个命名空间，用作其生成的 R 类 和 BuildConfig 类的 Kotlin 或 Java 包名称。从 AGP 7.3 开始，废弃清单文件中的 package 属性，建议在模块级 build.gradle 文件中使用 namespace 属性，从 AGP 8.0 开始，Gradle 开始强制要求使用 namespace 属性，用于取代 AndroidManifest 文件中的 package 属性。操作步骤如下：

• 移除每个 Module 的 AndroidManifest.xml 文件中的 package 属性：

  <?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
      xmlns:tools="http://schemas.android.com/tools"
      ~package="com.sofish.game"~>
  
  </manifest>
  

• 在每个 Module 的 build.gradle 文件中添加 namespace 属性：

  android {
      namespace "com.sofish.game"
      ...
  }
  

6.5 新的设置插件

AGP 8.0 引入了新的设置插件。设置插件可将全局配置（适用于所有模块的配置）集中在一处，无需在多个模块中复制并粘贴配置。要使用设置插件，需要在 settings.gradle 文件中应用该插件：

apply plugin 'com.android.settings'

要配置全局配置，请在 settings.gradle 文件中使用新的 android 块，示例如下：

android {
    minSdk 21
    compileSdk 34
    ...
}

6.6 构建选项默认值(变更)

从 AGP 8.0 开始，这些标志的默认值已更改以提高构建性能。要获得调整代码以支持其中一些更改的帮助，请使用 AGP Upgrade Assistant (Tools > AGP Upgrade Assistant)。升级助手将指导您更新代码以适应新行为或设置标志以保留以前的行为。

7. Gradle 声明版本和范围

项目中可以指定依赖项的确切版本或版本范围，以定义项目可以使用哪些版本：

dependencies {
    implementation 'org.springframework:spring-core:5.3.8'
    implementation 'org.springframework:spring-core:5.3.+'
    implementation 'org.springframework:spring-core:latest.release'
    implementation 'org.springframework:spring-core:[5.2.0, 5.3.8]'
    implementation 'org.springframework:spring-core:[5.2.0,)'
}

7.1 理解版本声明

Gradle 支持多种声明版本和范围的方式：

7.2 依赖关系解析策略

7.2.1 设置缓存时间

默认情况下，动态版本和快照版本的缓存会保留 24 小时，之后缓存条目过期，依赖版本会重新解析。以下配置可设置自定义过期时间：

configurations.configureEach {
    resolutionStrategy {
        // 动态版本设置为缓存10分钟
        cacheDynamicVersionsFor 10, 'minutes'
        // 快照版本设置为完全不缓存
        cacheChangingModulesFor 0, 'seconds'
    }
}

7.2.2 强制使用特定版本

允许强制使用特定版本的依赖项，包括传递依赖项。以下配置可设置强制使用特定版本：

configurations.configureEach {
    resolutionStrategy {
        // 强制使用特定版本的依赖项（包括传递依赖项）
        force 'asm:asm-all:3.3.1', 'commons-io:commons-io:1.4'
    }
}