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