通过 Android Studio 中的 Gradle 构建系统,您可以将外部二进制文件或其他库模块作为依赖项添加到 build 中。这些依赖项可位于您的计算机上或远程仓库中,并且它们声明的所有传递依赖项也会自动包含在内。 本页介绍了如何在 Android 项目中使用依赖项,包括有关 Android Gradle 插件 (AGP) 特有的行为和配置的详细信息。如需更深入地了解 Gradle 依赖项的概念,您还应该参阅 Gradle 依赖项管理指南。但请注意,您的 Android 项目只能使用本页上定义的依赖项配置。
添加库或插件依赖项
添加和管理 build 依赖项的最佳方法是使用版本目录,这是新项目默认使用的方法。本部分涵盖了 Android 项目最常用的配置类型;如需更多选项,请参阅 Gradle 文档。如需查看使用版本目录的应用示例,请参阅 Now in Android。如果您已经在不使用版本目录的情况下设置了 build 依赖项,并且拥有多模块项目,我们建议您进行迁移。
如需有关添加和管理原生依赖项(不常见)的指导,请参阅原生依赖项。
在以下示例中,我们为项目添加了远程二进制文件依赖项(Jetpack Macrobenchmark 库)、本地库模块依赖项 (myLibrary
) 和插件依赖项(Android Gradle 插件)。以下是将这些依赖项添加到项目的常规步骤:
在版本目录文件的
[versions]
部分为所需依赖项版本添加一个别名libs.versions.toml
(位于 Project 视图的gradle
目录下或 Android 视图中的 Gradle Scripts 下):[versions] agp = "8.3.0" androidx-macro-benchmark = "1.2.2" my-library = "1.4" [libraries] ... [plugins] ...
别名可包含短划线或下划线。这些别名会生成可在 build 脚本中引用的嵌套值。这些参考文档以目录(即
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 对库系列及其版本进行了分组。您可以在版本目录和 build 文件中添加 BoM,让它为您管理这些版本。如需了解详情,请参阅使用物料清单。
向需要依赖项的模块的 build 脚本添加对依赖项别名的引用。从 build 脚本引用别名时,请将其下划线和短划线转换为英文句点。我们的模块级构建脚本如下所示:
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 会将依赖项添加到编译类路径,并将依赖项打包到 build 输出。当您的模块配置 implementation 依赖项时,会让 Gradle 了解您不希望该模块在编译时将该依赖项泄露给其他模块。也就是说,依赖当前模块的其他模块无法使用该依赖项。
使用此依赖项配置代替 |
api |
Gradle 会将依赖项添加到编译类路径和 build 输出。当一个模块包含 api 依赖项时,会让 Gradle 了解该模块要以传递方式将该依赖项导出到其他模块,以便这些模块在运行时和编译时都可以使用该依赖项。
请谨慎使用此配置,并且仅将其用于您需要以传递方式导出到其他上游消费者的依赖项。如果 |
compileOnly |
Gradle 只会将依赖项添加到编译类路径(也就是说,不会将其添加到 build 输出)。如果您创建 Android 模块,并且在编译期间需要该依赖项,但在运行时可有可无,此依赖项可视需要进行设置。例如,如果您依赖的库仅包含编译时注解(通常用于生成代码,但通常未包含在 build 输出中),则可以将该库标记为 compileOnly 。
如果您使用此配置,那么您的库模块必须包含一个运行时条件,用于检查是否提供了相应依赖项,然后适当地改变该模块的行为,以使该模块在未提供相应依赖项的情况下仍可正常运行。这样做不会添加不重要的瞬时依赖项,因而有助于减小最终应用的大小。
注意:您不能将 |
runtimeOnly |
Gradle 只会将依赖项添加到 build 输出,以便在运行时使用。也就是说,不会将其添加到编译类路径。
这在 Android 上很少使用,但常用于服务器应用来提供日志记录实现。例如,库可以使用不包含实现的日志记录 API。该库的使用方可将其添加为 implementation 依赖项,并在实际的日志记录实现中包含 runtimeOnly 依赖项。
|
ksp |
这些配置提供的库会在系统编译代码之前处理代码中的注解和其他符号。它们通常会验证您的代码或生成其他代码,从而减少您需要编写的代码。 如需添加此类依赖项,您必须使用 如果 JAR 文件包含以下文件,则 Android Gradle 插件会假定依赖项是注解处理器:
如果插件检测到编译类路径上包含注解处理器,则会产生 build 错误。
在决定要使用哪项配置时,请考虑以下因素:
如需详细了解如何使用注解处理器,请参阅添加注解处理器。 |
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') } |
为特定 build 变体配置依赖项
上述所有配置会将依赖项应用于所有 build 变体。如果您只想为特定的 build 变体源代码集或测试源代码集声明依赖项,则必须将配置名称的首字母大写,并在其前面加上 build 变体或测试源代码集的名称作为前缀。
例如,如需使用 implementation
配置仅将远程二进制文件依赖项添加到“free”产品变种,请使用以下代码:
Kotlin
dependencies { freeImplementation("com.google.firebase:firebase-ads:21.5.1") }
Groovy
dependencies { freeImplementation 'com.google.firebase:firebase-ads:21.5.1' }
不过,如果您想为将产品变种和 build 类型组合在一起的变体添加依赖项,则必须初始化配置名称:
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.5.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.5.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 会在版本目录文件和 Google Play SDK 索引中针对公共 SDK 的“Project Structure”对话框中显示 lint 警告:
- 这些 SDK 已被作者标记为过时。
- SDK 违反了 Play 政策。
这些警告表示您应更新这些依赖项,因为使用过时的版本可能会导致您日后无法发布到 Google Play 管理中心。
在不使用版本目录的情况下添加 build 依赖项
我们建议您使用版本目录来添加和管理依赖项,但简单的项目可能不需要这些目录。下面是一个不使用版本目录的 build 文件示例:
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') }
此 build 文件在“com.example.android”命名空间组内声明了对 12.3 版“app-magic”库的依赖关系。远程二进制依赖项声明是以下内容的简写:
Kotlin
implementation(group = "com.example.android", name = "app-magic", version = "12.3")
Groovy
implementation group: 'com.example.android', name: 'app-magic', version: '12.3'
build 文件还声明了对一个名为“mylibrary”的 Android 库模块的依赖项;此名称必须与 settings.gradle.kts
文件中使用 include:
定义的库名称一致。在构建应用时,构建系统会编译该库模块,并将生成的编译内容打包到应用中。
build 文件还声明了对 Android Gradle 插件的依赖项 (com.application.android
)。如果您有多个模块使用同一个插件,则在所有模块的 build 类路径上只能有一个版本的插件。您应将插件依赖项与版本一起添加到根 build 脚本中,并指明不要应用该插件,而不是在每个模块 build 脚本中指定版本。添加 apply false
会告知 Gradle 记下插件的版本,但不要在根 build 中使用它。通常,除了这个 plugins
代码块之外,根 build 脚本是空的。
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' }