添加 build 依赖项

通过 Android Studio 中的 Gradle 构建系统,您可以将外部二进制文件或其他库模块作为依赖项添加到 build 中。这些依赖项可位于您的计算机上或远程仓库中,并且它们声明的所有传递依赖项也会自动包含在内。 本页介绍了如何在 Android 项目中使用依赖项,包括有关 Android Gradle 插件 (AGP) 特有的行为和配置的详细信息。如需更深入地了解 Gradle 依赖项的概念,您还应该参阅 Gradle 依赖项管理指南。但请注意,您的 Android 项目只能使用本页上定义的依赖项配置

添加库或插件依赖项

添加和管理 build 依赖项的最佳方法是使用版本目录,这是新项目默认使用的方法。本部分涵盖了 Android 项目最常用的配置类型;如需更多选项,请参阅 Gradle 文档。如需查看使用版本目录的应用示例,请参阅 Now in Android。如果您已经在不使用版本目录的情况下设置了 build 依赖项,并且拥有多模块项目,我们建议您进行迁移

如需有关添加和管理原生依赖项(不常见)的指导,请参阅原生依赖项

在以下示例中,我们为项目添加了远程二进制文件依赖项Jetpack Macrobenchmark 库)、本地库模块依赖项 (myLibrary) 和插件依赖项(Android Gradle 插件)。以下是将这些依赖项添加到项目的常规步骤:

  1. 在版本目录文件的 [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.tomllibs 部分)的名称开头。使用单个版本目录时,我们建议您保留默认值“libs”。

  2. 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,让它为您管理这些版本。如需了解详情,请参阅使用物料清单

  3. 向需要依赖项的模块的 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 限定符,因此您无法在库别名开头使用 versionsplugins

配置依赖项

dependencies 代码块内,您可以使用几种不同的依赖项配置(例如之前显示的 implementation)中的一种来声明库依赖项。每种依赖项配置都向 Gradle 提供了有关如何使用该依赖项的不同说明。下表介绍了您可以对 Android 项目中的依赖项使用的各种配置。

配置 行为
implementation Gradle 会将依赖项添加到编译类路径,并将依赖项打包到 build 输出。当您的模块配置 implementation 依赖项时,会让 Gradle 了解您不希望该模块在编译时将该依赖项泄露给其他模块。也就是说,依赖当前模块的其他模块无法使用该依赖项。

使用此依赖项配置代替 api 可以显著缩短构建时间,因为它可以减少构建系统需要重新编译的模块数。例如,如果 implementation 依赖项更改了其 API,Gradle 只会重新编译该依赖项以及直接依赖于它的模块。大多数应用和测试模块都应使用此配置。

api Gradle 会将依赖项添加到编译类路径和 build 输出。当一个模块包含 api 依赖项时,会让 Gradle 了解该模块要以传递方式将该依赖项导出到其他模块,以便这些模块在运行时和编译时都可以使用该依赖项。

请谨慎使用此配置,并且仅将其用于您需要以传递方式导出到其他上游消费者的依赖项。如果 api 依赖项更改了其外部 API,Gradle 会在编译时重新编译有权访问该依赖项的所有模块。拥有大量的 api 依赖项会显著增加构建时间。除非要将依赖项的 API 公开给单独的模块,否则库模块应改用 implementation 依赖项。

compileOnly Gradle 只会将依赖项添加到编译类路径(也就是说,不会将其添加到 build 输出)。如果您创建 Android 模块,并且在编译期间需要该依赖项,但在运行时可有可无,此依赖项可视需要进行设置。例如,如果您依赖的库仅包含编译时注解(通常用于生成代码,但通常未包含在 build 输出中),则可以将该库标记为 compileOnly

如果您使用此配置,那么您的库模块必须包含一个运行时条件,用于检查是否提供了相应依赖项,然后适当地改变该模块的行为,以使该模块在未提供相应依赖项的情况下仍可正常运行。这样做不会添加不重要的瞬时依赖项,因而有助于减小最终应用的大小。

注意:您不能将 compileOnly 配置与 Android ARchive (AAR) 依赖项一起使用。

runtimeOnly Gradle 只会将依赖项添加到 build 输出,以便在运行时使用。也就是说,不会将其添加到编译类路径。 这在 Android 上很少使用,但常用于服务器应用来提供日志记录实现。例如,库可以使用不包含实现的日志记录 API。该库的使用方可将其添加为 implementation 依赖项,并在实际的日志记录实现中包含 runtimeOnly 依赖项。
ksp
kapt
annotationProcessor

这些配置提供的库会在系统编译代码之前处理代码中的注解和其他符号。它们通常会验证您的代码或生成其他代码,从而减少您需要编写的代码。

如需添加此类依赖项,您必须使用 kspkaptannotationProcessor 配置将其添加到注解处理器类路径。使用这些配置可以将编译类路径与注解处理器类路径分开,从而提高构建性能。如果 Gradle 在编译类路径上找到注解处理器,则会禁用 避免编译功能,这样会对构建时间产生负面影响(Gradle 5.0 及更高版本会忽略在编译类路径上找到的注解处理器)。

如果 JAR 文件包含以下文件,则 Android Gradle 插件会假定依赖项是注解处理器:

META-INF/services/javax.annotation.processing.Processor

如果插件检测到编译类路径上包含注解处理器,则会产生 build 错误。

ksp 是一个 Kotlin Symbol Processor,由 Kotlin 编译器运行。

kaptapt 是不同的工具,它们会在 Kotlin 或 Java 编译器执行之前处理注解。

在决定要使用哪项配置时,请考虑以下因素:

  • 如果处理器可用作 Kotlin Symbol Processor,则将其用作 ksp 依赖项。 如需详细了解如何使用 Kotlin 符号处理器,请参阅从 kapt 迁移到 ksp
  • 如果该处理器无法用作 Kotlin Symbol Processor,请执行以下操作:
    • 如果您的项目包含 Kotlin 源代码(但也可以包含 Java 源代码),请使用 kapt 添加该源代码。
    • 如果您的项目仅使用 Java 源代码,请使用 annotationProcessor 添加该源代码。

如需详细了解如何使用注解处理器,请参阅添加注解处理器

lintChecks

使用此配置可以添加一个库,其中包含您希望 Gradle 在构建 Android 应用项目时执行的 lint 检查。

请注意,包含 lint.jar 文件的 AAR 将自动运行在该 lint.jar 文件中定义的检查;您无需添加明确的 lintChecks 依赖项。 这样,您就可以在单个依赖项中定义库和关联的 lint 检查,从而确保在消费者使用您的库时运行这些检查。

lintPublish 在 Android 库项目中使用此配置可以添加您希望 Gradle 编译成 lint.jar 文件并打包在 AAR 中的 lint 检查。这会使得使用 AAR 的项目也应用这些 lint 检查。如果您之前使用 lintChecks 依赖项配置将 lint 检查添加到已发布的 AAR 中,则需要迁移这些依赖项以改用 lintPublish 配置。

Kotlin

dependencies {
  // 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"))
}

Groovy

dependencies {
  // 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_ALIB_B(按此顺序)
  • LIB_A 依赖于 LIB_CLIB_D(按此顺序)
  • LIB_B 也依赖于 LIB_C

那么,扁平型依赖项顺序将如下所示:

  1. LIB_A
  2. LIB_D
  3. LIB_B
  4. LIB_C

这可以确保 LIB_ALIB_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'
}