Android Gradle 插件 8.1.0（2023 年 7 月）

Android Gradle 插件 8.1.0 是一个主要版本，包含各种新功能和改进。

兼容性

	最低版本	默认版本	备注
Gradle	8.0	8.0	如需了解详情，请参阅更新 Gradle。
SDK Build Tools	33.0.1	33.0.1	安装或配置 SDK Build Tools。
NDK	不适用	25.1.8937393	安装或配置其他版本的 NDK。
JDK	17	17	如需了解详情，请参阅设置 JDK 版本。

Kotlin DSL 是 build 配置的默认语言

新项目现在默认使用 Kotlin DSL (build.gradle.kts) 进行 build 配置。与 Groovy DSL (build.gradle) 相比，这提供了更好的编辑体验，包括语法突出显示、代码补全和导航到声明。请注意，如果您使用 AGP 8.1 和 Kotlin DSL 进行构建配置，则应使用 Gradle 8.1 以获得最佳体验。如需了解详情，请参阅 Kotlin DSL 迁移指南。

各应用自动设定语言支持

注意：此功能不会像手动设置流程一样对项目进行更改。自动流程中的所有更改都是在生成的文件中完成的。例如，您不会在应用的清单中看到 android:localeConfig 条目，也不会在 res/xml/locales_config.xml 看到文件。这是预期行为，因为所有更改都是在构建应用时自动生成的。

从 Android Studio Giraffe Canary 7 和 AGP 8.1.0-alpha07 开始，您可以将应用配置为自动支持各应用语言偏好设定。Android Gradle 插件会根据您的项目资源生成 LocaleConfig 文件，并在最终清单文件中添加对该文件的引用，这样您就不再需要手动操作。AGP 使用应用模块的 res 文件夹中的资源以及任何库模块依赖项来确定要在 LocaleConfig 文件中添加的语言区域。

请注意，各应用自动语言功能支持搭载 Android 13（API 级别 33）或更高版本的应用。如需使用此功能，您必须将 compileSdkVersion 设为 33 或更高版本。如需为之前版本的 Android 配置各应用语言偏好设定，您仍然需要使用 API 和应用内语言选择器。

注意：如果您为生产环境中的应用启用了启用各应用自动设定语言支持，请确保应用和库模块依赖项资源中的所有语言区域也可与您的应用一起发布。

如需启用各应用自动设定语言支持，请指定默认语言区域：

1. 在应用模块的 res 文件夹中，创建一个名为 resources.properties 的新文件。

2. 在 resources.properties 文件中，使用 unqualifiedResLocale 标签设置默认语言区域。将语言代码与可选的脚本代码和区域代码（使用短划线将各部分隔开）组合在一起即可构成语言区域名称：

   • 语言：使用由两个或三个字母组成的 ISO 639-1 代码。
   • 脚本（可选）：使用 ISO 15924 代码。
   • 区域（可选）：使用由两个字母组成的 ISO 3166-1-alpha-2 代码或三位数的 UN_M.49 代码。

   例如，如果您的默认语言区域是美式英语：

       unqualifiedResLocale=en-US
       

AGP 会将此默认语言区域和您指定的所有其他语言区域（使用 res 文件夹中的 values-* 目录）添加到自动生成的 LocaleConfig 文件中。

注意 ：在启用了各应用自动设定语言支持的情况下，如果您手动创建 LocaleConfig 文件，构建会失败。您必须先移除手动创建的 LocaleConfig 文件，然后才能启用各应用自动设定语言支持和构建应用。

各应用自动设定语言支持功能默认处于关闭状态。如需启用此功能，请使用模块级 build.gradle.kts 文件（如果您使用的是 Groovy，则为 build.gradle 文件）的 androidResources {} 块中的 generateLocaleConfig 设置：

Kotlin

android {
  androidResources {
    generateLocaleConfig = true
  }
}

Groovy

android {
  androidResources {
    generateLocaleConfig true
  }
}

Android Lint 包含以 JVM 17 为目标的字节码

从 AGP 8.1.0-alpha04 开始，Android Lint 包含以 JVM 17 为目标平台的字节码。如果您编写自定义 lint 检查，则需要使用 JDK 17 或更高版本进行编译，并在 Kotlin 编译器选项中指定 jvmTarget = '17'。

如需详细了解 lint 工具，请参阅使用 lint 检查改进您的代码。

原生库压缩设置已移至 DSL

从 AGP 8.1.0-alpha10 开始，如果您未使用 DSL（而非清单）配置原生库压缩，则会收到警告。以下指南介绍了如何更新配置以使用 DSL。如需获取进行这些更新方面的帮助，请使用 AGP 升级助理 (Tools > AGP Upgrade Assistant)。

注意 ：useLegacyPackaging DSL 仅支持生成 APK 的模块。如需为库模块配置原生库压缩，请继续使用 extractNativeLibs 清单属性；您无需使用 DSL 添加任何内容。

如需使用未压缩的原生库，请从清单中移除 android::extractNativeLibs 属性，并将以下代码添加到模块级 build.gradle.kts 文件（如果您使用的是 Groovy，则为 build.gradle 文件）：

Kotlin

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging = false
    }
  }
}

Groovy

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging false
    }
  }
}

实验性 build 标志

这些是用于配置 AGP 8.1 中提供的 build 的实验性标志。

标志	添加时间	默认值	备注
android.experimental.useDefaultDebugSigningConfigForProfileableBuildtypes	AGP 8.0	false	如果启用此功能但未指定签名配置，则 AGP 会在运行可分析或可调试 build 时使用默认调试签名配置。此标志默认处于停用状态，以鼓励 build 作者声明特定的性能分析签名配置。
android.experimental.library.desugarAndroidTest	AGP 8.0	false	借助此标志，库构建器可以为测试 APK 启用核心库脱糖，而不会影响生成的 AAR（例如通过 lint 检查）。我们计划最终在 Variant API 中支持此行为。
android.experimental.testOptions.managedDevices.customDevice	AGP 8.0	false	启用后，Gradle 管理的设备允许使用插件提供的用户定义的自定义设备类型。如果您想使用 Firebase Test Lab 插件，则必须启用此标志。
android.lint.printStackTrace	AGP 8.0	false	如果启用，Android lint 会在崩溃时输出堆栈轨迹。此标志的功能与 LINT_PRINT_STACKTRACE 环境变量相同。
android.experimental.testOptions.managedDevices.maxConcurrentDevices	AGP 8.0	无	指定任意时间点处于活动状态的 Gradle 受管设备 (AVD) 的并发数量上限。如果值为 0 或负数，则表示没有设备数量上限。
android.experimental.testOptions.installApkTimeout	AGP 8.0	无	安装 APK 的超时时长（以秒为单位）。如果该值为 0 或负数，UTP 会将其设置为默认值。

修复的问题

Android Gradle 插件 8.1.0

已修复的问题
Android Gradle 插件	问题 263576736 配置缓存的“com.android.build.gradle.tasks.ShaderCompile”问题 问题 263469991 使用 AGP API 添加到 Java 资源会破坏配置缓存 问题 257976107 [Android Studio：Flamingo | 2022.2.1 Canary 8] liblog.so 打包在 APK 内 问题 263575963 KGP 在配置期间读取清单，在清单发生更改时使配置缓存失效 问题 259995135 合并后的清单中存在问题时，构建警告消息不明确 问题 265385297 升级到 AGP 7.4 会导致 StackOverflowError 问题 246326007 直接依赖于 Kotlin 库子项目的动态功能中的 ClassNotFoundException 问题 266967487 测试变体中的清单占位符导致 processDebugUnitTestManifest 失败 问题 266967487 测试变体中的清单占位符导致 processDebugUnitTestManifest 失败 问题 266135619 命名空间属性可能属于 HasAndroidResources 问题 242051158 无法停用“Gradle files have changed since last project sync”消息 问题 227796082 没有更高版本的插件时显示“We recommend using a newer Android Gradle plugin” 问题 266967487 测试变体中的清单占位符导致 processDebugUnitTestManifest 失败 问题 269759002 用于在 CheckAarMetadataTask 中停用编译 SDK 检查的布尔标志 问题 269598545 构建错误涉及不存在的 API 级别 34 问题 260059413 设置 JVM 工具链不会影响 JavaCompile targetCompatibility 值 问题 268128036 包含通配符网域的导航深层链接条目在合并后的清单中没有“android:host”属性 问题 270201653 自 Android Gradle 插件 8.1 开始，processDebugMainManifest 任务会失败 问题 269758603 我们能否移除 AnalyticsRecordingTask？ 问题 258621110 output-metadata.json 的内容不一致 问题 269758603 我们能否移除 AnalyticsRecordingTask？ 问题 258621110 output-metadata.json 的内容不一致 问题 260059413 设置 JVM 工具链不会影响 JavaCompile targetCompatibility 值 问题 268128036 包含通配符网域的导航深层链接条目在合并后的清单中没有“android:host”属性 问题 270201653 自 Android Gradle 插件 8.1 开始，processDebugMainManifest 任务会失败 问题 213266836 Android Studio 不遵循 STUDIO_GRADLE_JDK 环境变量 问题 268192807 自定义源代码类型应创建多变种源代码集 问题 274913388 DependenciesInfoBuilder 需要 API 更新 + 文档 问题 266599585 由于缺少嵌套成员，带 Java 11 目标的 DexingNoClasspathTransform (minSdk >= 24) 执行失败 问题 260100335 DslExtension.Builder.extendProjectWith() 在 Groovy 中无法像所描述的那样运行 问题 265336046 添加不使用 kotlin.Pair 的 VariantSelector.withFlavor API 问题 #266403349 AndroidLintAnalysisTask (:lintAnalyzeExternalRelease) 缓存未命中，原因是“proguard.txt”已发生更改 问题 272553504 应用合并后的清单包含依赖项中的 extractNativeLibs 属性和 useEmbeddedDex 属性 问题 268237729 AGP：将 AIDL 工具和框架 AIDL 文件的路径显示为公共 API 问题 274016286 请求：让 IDE 修复“PermittedSubclasses requires ASM9” 问题 279954562 bug：按照“启用 KSP 并改为针对此依赖项使用 KSP 处理器”后，只会前往某个网站 问题 278767328 Gradle 8.1 会因 .gradle/.android/analytics.settings 而破坏配置缓存 问题 281825213 agp 8.1.0 中的 generateLocaleConfig 使用非确定性排序，破坏了可重现的 build
Dexer (D8)	问题 266687543 核心库在近期更新后使崩溃应用脱糖。 问题 279780940 agp 8.1.0 在与 API 21 结合使用时发生回归 - F/dex2oat ( 4176): art/compiler/driver/compiler_driver.cc:1181] Check failed: !method->IsAbstract()
lint	问题 263526184 lint 仅会针对直接实现的接口（而非继承的接口）检查安全类型转换 问题 263526227 lint 不会检查调用接收器的有效类型转换 问题 262851206 TypedArray#close (API 31) 未进行脱糖，但在 try-with-resources 中使用时，AS 不显示警告 问题 263115741 bug：“‘BC’提供程序已废弃，自 Android P 起…”误报警告 问题 263887242 在升级到 Kotlin 1.8.0 后，关于 remember 的 lint 检查出现误报 问题 239767506 在包含枚举参数的方法内执行的 SDK_INT 检查出现误报 lint 警告 问题 269323652 TypographyQuotes lint 检查对转义引号不起作用 问题 270065082 TrustAllX509TrustManager lint 检查会错误地标记扩展 X509TrustManager 的接口 问题 242557502 仅重新设置替换修复程序的插入代码的格式 问题 271575376 lint：意图预览会针对 replaceStringQuickFix 抛出异常
缩减器 (R8)	问题 278573402 VerifyError：将 R8 与 Kotlin 1.8.20 结合使用时，验证程序会拒绝类 问题 280659987 AGP 8 上的 R8 会破坏 Google 健身服务 问题 279702361 如果包含的源文件信息存在与输入名称重叠的残留名称，则无法正确显示 问题 280904554 R8 在 Compose 构建期间失败并抛出 ArrayIndexOutOfBoundsException 问题 280958704 简单的 StringBuilder 相关代码在 release 或 debuggable=false 模式中缺少对 append 的尾调用 问题 284188592 VirtualDispatchMethodArgumentPropagator.shouldActivateMethodStateGuardedByBounds() 方法中存在极端情况 问题 284334258 dex-startup-optimization 导致 java.lang.VerifyError：拒绝类 问题 283715197 Android 12 及更高版本上发生崩溃并出现验证错误

Android Gradle 插件 8.1.1

已修复的问题
Dexer (D8)	问题 289237734 Java 16 记录：equals(null) 会抛出 NullPointerException
缩减器 (R8)	问题 293501981 java.lang.VerifyError: Verifier rejected class 问题 295349278 使用 Apache POI 库时，Build 会在 :minifyReleaseWithR8 上卡住 问题 291130232 启用 r8 优化时拒绝调用 问题 289361079 java.lang.reflect.Executable 的 NoClassDefFoundError

Android Gradle 插件 8.1.2

已修复的问题
Android Gradle 插件	问题 294771624 Android 库模块中不提供 androidResources 问题 293547829 [AGP 8.1.0] 如果 splits.abi.isEnable 和 testOptions.unitTests.isIncludeAndroidResources 均为 True，则 ./gradlew 测试会失败，并且会显示消息“Unable to find manifest output”
缩减器 (R8)	问题 295576241 如果去除 null 检查，Kotlin 1.9 会导致 R8 销毁 Kotlin lambda 问题 296654327 针对 play-services-measurement-21.3.0-runtime.jar，R8 失败并显示“编译期间遇到未定义值”

Android Gradle 插件 8.1.3

已修复的问题
Android Gradle 插件	问题 293547829 [AGP 8.1.0] 如果 splits.abi.isEnable 和 testOptions.unitTests.isIncludeAndroidResources 均为 True，则 ./gradlew 测试会失败，并且会显示消息“Unable to find manifest output” 问题 304082728 更新到 AGP 8.1 后 build 失败

Android Gradle 插件 8.1.4

已修复的问题
Android Gradle 插件	问题 310252873 如果子项目的类已通过工件转换进行 dex 处理，不对这些类运行 dexing 任务