Android Studio 中的 Gradle 构建系统允许您将外部二进制文件或其他库模块作为依赖项包含在构建中。这些依赖项可以位于您的机器上,也可以位于远程仓库中,并且它们声明的任何传递性依赖项也会自动包含在内。本页面介绍了如何在 Android 项目中使用依赖项,包括 Android Gradle 插件 (AGP) 特定的行为和配置的详细信息。有关 Gradle 依赖项的更深入概念指南,请参阅 Gradle 依赖项管理指南,但请记住,您的 Android 项目必须仅使用本页面定义的依赖项配置。
添加库或插件依赖项
添加和管理构建依赖项的最佳方法是使用版本目录,这是新项目默认使用的方法。本部分介绍了 Android 项目最常用的配置类型;如需了解更多选项,请参阅 Gradle 文档。如需查看使用版本目录的应用示例,请参阅 Now in Android。如果您已经设置了不使用版本目录的构建依赖项,并且拥有一个多模块项目,我们建议进行迁移。
有关添加和管理原生依赖项(不常见)的指南,请参阅原生依赖项。
在以下示例中,我们将一个远程二进制依赖项(Jetpack Macrobenchmark 库)、一个本地库模块依赖项(myLibrary
)和一个插件依赖项(Android Gradle 插件)添加到我们的项目。以下是将这些依赖项添加到项目的一般步骤
在版本目录文件(名为
libs.versions.toml
,位于 Project 视图中的gradle
目录下或 Android 视图中的 Gradle Scripts 中)的[versions]
部分中,为您所需的依赖项版本添加一个别名[versions] agp = "8.3.0" androidx-macro-benchmark = "1.2.2" my-library = "1.4" [libraries] ... [plugins] ...
别名可以包含短划线或下划线。这些别名会生成您可以在构建脚本中引用的嵌套值。引用以目录名称开头,即
libs.versions.toml
中的libs
部分。使用单个版本目录时,我们建议保留默认值“libs”。在
libs.versions.toml
文件的[libraries]
(用于远程二进制文件或本地库模块)或[plugins]
(用于插件)部分中,为依赖项添加一个别名。[versions] ... [libraries] androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" } my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" } [plugins] androidApplication = { id = "com.android.application", version.ref = "agp" }
某些库在已发布的物料清单 (BOM) 中提供,这些 BOM 将库系列及其版本分组。您可以在版本目录和构建文件中包含 BOM,并让它为您管理这些版本。如需了解详情,请参阅使用物料清单。
将依赖项别名引用添加到需要该依赖项的模块的构建脚本中。从构建脚本中引用别名时,将其下划线和短划线转换为点。我们的模块级构建脚本如下所示
Kotlin
plugins { alias(libs.plugins.androidApplication) } dependencies { implementation(libs.androidx.benchmark.macro) implementation(libs.my.library) }
Groovy
plugins { alias 'libs.plugins.androidApplication' } dependencies { implementation libs.androidx.benchmark.macro implementation libs.my.library }
插件引用在目录名称后包含
plugins
,版本引用在目录名称后包含versions
(版本引用不常见;有关版本引用的示例,请参阅具有相同版本号的依赖项)。库引用不包含libraries
限定符,因此您不能在库别名的开头使用versions
或plugins
。
配置依赖项
在 dependencies
块内,您可以使用几种不同的依赖项配置之一(例如前面所示的 implementation
)声明库依赖项。每个依赖项配置都向 Gradle 提供有关如何使用该依赖项的不同说明。下表描述了您可以在 Android 项目中用于依赖项的每种配置。
配置 | 行为 |
---|---|
implementation |
Gradle 会将依赖项添加到编译类路径中,并将依赖项打包到构建输出中。当您的模块配置 implementation 依赖项时,它会告知 Gradle,您不希望该模块在编译时将依赖项泄漏给其他模块。也就是说,该依赖项不会提供给依赖当前模块的其他模块。使用此依赖项配置而不是 |
api |
Gradle 会将依赖项添加到编译类路径和构建输出中。当模块包含 api 依赖项时,它会告知 Gradle,该模块希望将该依赖项传递性地导出到其他模块,以便其他模块在运行时和编译时都可以使用它。谨慎使用此配置,并且仅用于您需要传递性导出到其他上游消费者的依赖项。如果 |
compileOnly |
Gradle 仅将依赖项添加到编译类路径(即,不添加到构建输出)。这在您创建 Android 模块时很有用,您在编译期间需要该依赖项,但在运行时它可有可无。例如,如果您依赖一个只包含编译时注解的库(通常用于生成代码,但通常不包含在构建输出中),则可以将该库标记为 compileOnly 。
如果您使用此配置,那么您的库模块必须包含一个运行时条件来检查依赖项是否可用,然后优雅地改变其行为,以便在未提供依赖项的情况下它仍然可以正常运行。这有助于通过不添加不重要的传递性依赖项来减小最终应用的大小。
注意:您不能将 |
runtimeOnly |
Gradle 仅将依赖项添加到构建输出中,供运行时使用。也就是说,它不会添加到编译类路径中。这在 Android 上很少使用,但在服务器应用程序中通常用于提供日志记录实现。例如,一个库可以使用不包含实现的日志记录 API。该库的消费者可以将其添加为 implementation 依赖项,并包含一个 runtimeOnly 依赖项,以供实际的日志记录实现使用。 |
ksp |
这些配置提供了在代码编译之前处理注解和其他符号的库。它们通常用于验证代码或生成额外的代码,从而减少您需要编写的代码量。 要添加此类依赖项,您必须使用 如果依赖项的 JAR 文件包含以下文件,则 Android Gradle 插件会将其视为注解处理器
如果插件检测到编译类路径上存在注解处理器,则会产生构建错误。
在决定使用哪种配置时,请考虑以下事项
有关使用注解处理器的更多信息,请参阅添加注解处理器。 |
lintChecks |
使用此配置可包含一个库,其中包含您希望 Gradle 在构建 Android 应用项目时执行的 lint 检查。 请注意,包含 |
lintPublish |
在 Android 库项目中使用此配置,以包含您希望 Gradle 编译到 lint.jar 文件并打包到您的 AAR 中的 lint 检查。这将导致使用您的 AAR 的项目也应用这些 lint 检查。如果您之前使用 lintChecks 依赖项配置将 lint 检查包含在已发布的 AAR 中,则需要将这些依赖项迁移为使用 lintPublish 配置。Kotlindependencies { // Executes lint checks from the ":checks" project at build time. lintChecks(project(":checks")) // Compiles lint checks from the ":checks-to-publish" into a // lint.jar file and publishes it to your Android library. lintPublish(project(":checks-to-publish")) } Groovydependencies { // Executes lint checks from the ':checks' project at build time. lintChecks project(':checks') // Compiles lint checks from the ':checks-to-publish' into a // lint.jar file and publishes it to your Android library. lintPublish project(':checks-to-publish') } |
配置特定构建变体的依赖项
所有上述配置都将依赖项应用于所有构建变体。如果您只想为特定的构建变体源集或测试源集声明依赖项,则必须将配置名称大写,并在其前面加上构建变体或测试源集的名称。
例如,要使用 implementation
配置仅将远程二进制依赖项添加到您的“free”产品变种,请使用此项
Kotlin
dependencies { freeImplementation("com.google.firebase:firebase-ads:21.5.1") }
Groovy
dependencies { freeImplementation 'com.google.firebase:firebase-ads:21.5.1' }
但是,如果您想为结合了产品变种和构建类型的变体添加依赖项,则必须初始化配置名称
Kotlin
// Initializes a placeholder for the freeDebugImplementation dependency configuration. val freeDebugImplementation by configurations.creating dependencies { freeDebugImplementation(project(":free-support")) }
Groovy
configurations { // Initializes a placeholder for the freeDebugImplementation dependency configuration. freeDebugImplementation {} } dependencies { freeDebugImplementation project(":free-support") }
要为本地测试和插桩测试添加 implementation
依赖项,如下所示
Kotlin
dependencies { // Adds a remote binary dependency only for local tests. testImplementation("junit:junit:4.12") // Adds a remote binary dependency only for the instrumented test APK. androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1") }
Groovy
dependencies { // Adds a remote binary dependency only for local tests. testImplementation 'junit:junit:4.12' // Adds a remote binary dependency only for the instrumented test APK. androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1' }
但是,在这种情况下,某些配置没有意义。例如,由于其他模块不能依赖于 androidTest
,因此如果您使用 androidTestApi
配置,则会收到以下警告
WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with 'androidTestImplementation'.
依赖项顺序
您列出依赖项的顺序表示每个依赖项的优先级:第一个库的优先级高于第二个,第二个高于第三个,依此类推。当从库中将资源合并或将清单元素合并到您的应用中时,此顺序非常重要。
例如,如果您的项目声明以下内容
- 依赖于
LIB_A
和LIB_B
(按此顺序) - 并且
LIB_A
依赖于LIB_C
和LIB_D
(按此顺序) - 并且
LIB_B
也依赖于LIB_C
那么,平坦依赖项顺序将如下所示
LIB_A
LIB_D
LIB_B
LIB_C
这确保了 LIB_A
和 LIB_B
都可以覆盖 LIB_C
;并且 LIB_D
的优先级仍然高于 LIB_B
,因为 LIB_A
(依赖于它)的优先级高于 LIB_B
。
有关如何合并来自不同项目源/依赖项的清单的更多信息,请参阅合并多个清单文件。
Play 管理中心依赖项信息
构建应用时,AGP 会包含描述编译到应用中的库依赖项的元数据。上传应用时,Play 管理中心会检查此元数据,以针对应用使用的 SDK 和依赖项的已知问题提供提醒,并在某些情况下提供可操作的反馈来解决这些问题。
数据经过压缩,由 Google Play 签名密钥加密,并存储在发布应用的签名块中。我们建议保留此依赖项文件,以获得安全和积极的用户体验。您可以通过在模块的 build.gradle.kts
文件中包含以下 dependenciesInfo
块来选择停用。
android {
dependenciesInfo {
// Disables dependency metadata when building APKs.
includeInApk = false
// Disables dependency metadata when building Android App Bundles.
includeInBundle = false
}
}
有关我们的政策以及依赖项潜在问题的更多信息,请参阅我们关于在应用中使用第三方 SDK 的支持页面。
SDK 洞察
当以下问题适用时,Android Studio 会在版本目录文件和 Project Structure Dialog 中显示 Google Play SDK 索引中公共 SDK 的 lint 警告
- SDK 被其作者标记为已过时。
- SDK 违反了 Play 政策。
- SDK 存在已知的安全漏洞。
- SDK 已被其作者弃用。
这些警告表明您应该更新这些依赖项,因为使用过时的版本可能会阻止您将来发布到 Google Play 管理中心。
不使用版本目录添加构建依赖项
我们建议使用版本目录来添加和管理依赖项,但简单的项目可能不需要它们。以下是一个不使用版本目录的构建文件示例
Kotlin
plugins { id("com.android.application") } android { ... } dependencies { // Dependency on a remote binary implementation("com.example.android:app-magic:12.3") // Dependency on a local library module implementation(project(":mylibrary")) }
Groovy
plugins { id 'com.android.application' } android { ... } dependencies { // Dependency on a remote binary implementation 'com.example.android:app-magic:12.3' // Dependency on a local library module implementation project(':mylibrary') }
此构建文件声明了对“com.example.android”命名空间组中“app-magic”库版本 12.3 的依赖项。远程二进制依赖项声明是以下内容的简写
Kotlin
implementation(group = "com.example.android", name = "app-magic", version = "12.3")
Groovy
implementation group: 'com.example.android', name: 'app-magic', version: '12.3'
此构建文件还声明了对名为“mylibrary”的Android 库模块的依赖项;此名称必须与您 settings.gradle.kts
文件中 include:
定义的库名称匹配。当您构建应用时,构建系统会编译库模块并将生成的编译内容打包到应用中。
此构建文件还声明了对 Android Gradle 插件(com.application.android
)的依赖项。如果您有多个模块使用相同的插件,则所有模块的构建类路径上只能有一个版本的插件。您不应在每个模块构建脚本中指定版本,而应将插件依赖项及其版本包含在根构建脚本中,并指明不应用它。添加 apply false
会告知 Gradle 记录插件的版本,但在根构建中不使用它。通常,除了此 plugins
块之外,根构建脚本是空的。
Kotlin
plugins { id("org.jetbrains.kotlin.android") version "1.9.0" apply false }
Groovy
plugins { id ‘com.android.application’ version ‘8.3.0-rc02’ apply false }
如果您是单模块项目,则可以在模块级构建脚本中明确指定版本,并将项目级构建脚本留空
Kotlin
plugins { id("com.android.application") version "8.3.0" }
Groovy
plugins { id 'com.android.application' version '8.3.0-rc02' }