添加构建依赖项

Android Studio 中的 Gradle 构建系统简化了将外部二进制文件或其他库模块作为依赖项加入构建的操作。 这些依赖项可能位于您的计算机上或远程代码库中，它们声明的任何传递依赖项也将自动包括在内。本页面介绍如何在您的 Android 项目中使用依赖项，包括有关 Android Plugin for Gradle 特有行为和配置的详细信息。 如需获得更深入的 Gradle 依赖项概念性指导，您还应参阅 Gradle 依赖项管理指南，但切记，您的 Android 项目只能使用本页面上定义的依赖项配置。

注意：指定依赖项时，不应使用动态版本号，比如 'com.android.tools.build:gradle:3.+'。 使用此功能，可能会导致意外版本更新和难以解析版本差异。

依赖项类型

要为您的项目添加依赖项，请在您的 build.gradle 文件的 dependencies 程序块中指定依赖项配置，例如 implementation。

例如，以下这个应用模块的 build.gradle 文件包括三种不同类型的依赖项：

1. apply plugin: 'com.android.application'

3. android { ... }

5. dependencies {
6. // Dependency on a local library module
7. implementation project(":mylibrary")

9. // Dependency on local binaries
10. implementation fileTree(dir: 'libs', include: ['*.jar'])

12. // Dependency on a remote binary
13. implementation 'com.example.android:app-magic:12.3'
14. }

其中每个依赖项配置都请求不同种类的库依赖项，如下所示：

• 本地库模块依赖项

1. implementation project(':mylibrary')

这段代码声明名为“mylibrary”的 Android 库模块的依赖项（该名称必须匹配使用 settings.gradle 文件中的 include: 定义的库名称）。 在构建您的应用时，构建系统会编译库模块，并将生成的编译内容打包到 APK中。

• 本地二进制文件依赖项

1. implementation fileTree(dir: 'libs', include: ['*.jar'])

Gradle 声明项目 module_name/libs/ 目录中 JAR 文件的依赖项（因为 Gradle 会读取 build.gradle 文件的相对路径）。

或者，您也可以像下面这样指定单独的文件：

1. implementation files('libs/foo.jar', 'libs/bar.jar')

• 远程二进制文件依赖项

1. implementation 'com.example.android:app-magic:12.3'

以上代码实际上是下列代码的缩写形式：

1. implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

这段代码声明“com.example.android”命名空间组内“app-magic”库 12.3 版本的依赖项。

注：与此类似的远程依赖项要求您声明相应的远程代码库，Gradle 应在其中寻找该库。 如果本地尚不存在该库，Gradle 会在构建需要它时（例如，当您点击 Sync Project with Gradle Files 或当您运行构建时）从远程站点获取该库。

依赖项配置

在 dependencies 代码块内，您可以使用几种不同依赖项配置中的一种（例如上文所示的 implementation）声明库依赖项。 每项依赖项配置都为 Gradle 提供有关如何使用依赖项的不同说明。下表介绍您可以在 Android 项目中对依赖项使用的每种配置。此表还将这些配置与自 Android Gradle Plugin 3.0.0 起弃用的配置进行比较。

以上配置适用于您的项目的主源集，该源集应用于所有构建不同类型。 如果您改为只想为特定构建不同类型源集或测试源集声明依赖项，则必须大写配置名称并在其前面加上构建不同类型或测试源集的名称作为前缀。

例如，要仅将 implementation 依赖项添加到您的“free”产品风格（使用远程二进制文件依赖项），需要使用下面这样的代码：

1. dependencies {
2. freeImplementation 'com.google.firebase:firebase-ads:9.8.0'
3. }

但如果想要为组合产品风格和构建类型的变体添加依赖项，则必须在 configurations 代码块中初始化配置名称。 以下示例向您的“freeDebug”构建变体添加 runtimeOnly 依赖项（使用本地二进制文件依赖项）：

1. configurations {
2. // Initializes a placeholder for the freeDebugRuntimeOnly dependency
3. // configuration.
4. freeDebugRuntimeOnly {}
5. }

7. dependencies {
8. freeDebugRuntimeOnly fileTree(dir: 'libs', include: ['*.jar'])
9. }

要为您的本地测试和设备化测试添加 implementation 依赖项，需要使用下面这样的代码：

1. dependencies {
2. // Adds a remote binary dependency only for local tests.
3. testImplementation 'junit:junit:4.12'

5. // Adds a remote binary dependency only for the instrumented test APK.
6. androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2'
7. }

但某些配置在这种情况下没有意义。 例如，由于其他模块无法依赖 androidTest，因此如果使用 androidTestApi 配置，则会收到以下警告：

1. WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
2. 'androidTestImplementation'.

添加注解处理器

如果将注解处理器添加到您的编译类路径，您将看到一条与以下消息类似的错误消息：

1. Error: Annotation processors must be explicitly declared now.

要解决此错误问题，请使用 annotationProcessor 配置您的依赖项，以在您的项目中添加注解处理器，如下所示：

1. dependencies {
2. // Adds libraries defining annotations to only the compile classpath.
3. compileOnly 'com.google.dagger:dagger:version-number'
4. // Adds the annotation processor dependency to the annotation processor classpath.
5. annotationProcessor 'com.google.dagger:dagger-compiler:version-number'
6. }

注：Android Plugin for Gradle 3.0.0+ 不再支持 android-apt 插件。

向注解处理器传递参数

如果需要向注解处理器传递参数，您可以在您的模块构建配置中使用 AnnotationProcessorOptions代码块。 例如，如果要以键值对形式传递原始数据类型，则可使用 argument 属性，如下所示：

1. android {
2. ...
3. defaultConfig {
4. ...
5. javaCompileOptions {
6. annotationProcessorOptions {
7. argument "key1", "value1"
8. argument "key2", "value2"
9. }
10. }
11. }
12. }

但在使用 Android Gradle Plugin 3.2.0 和更高版本时，您需要使用 Gradle CommandLineArgumentProvider 接口传递表示文件或目录的处理器参数。

使用 CommandLineArgumentProvider 可让您或注解处理器作者将增量构建属性类型注解应用于每个参数，从而提高增量构建和缓存干净构建的正确性和性能。

例如，下面的类可实现 CommandLineArgumentProvider 并注解处理器的每个参数。 此外，此示例也使用 Groovy 语言语法，且直接包含在模块的 build.gradle文件中。

注：通常，注解处理器作者会提供此类或有关如何编写这种类的说明。 这是因为每个参数均需指定正确的构建属性类型注解，才能按预期运行。

1. class MyArgsProvider implements CommandLineArgumentProvider {

3. // Annotates each directory as either an input or output for the
4. // annotation processor.
5. @InputFiles
6. // Using this annotation helps Gradle determine which part of the file path
7. // should be considered during up-to-date checks.
8. @PathSensitive(PathSensitivity.RELATIVE)
9. FileCollection inputDir

11. @OutputDirectory
12. File outputDir

14. // The class constructor sets the paths for the input and output directories.
15. MyArgsProvider(FileCollection input, File output) {
16. inputDir = input
17. outputDir = output
18. }

20. // Specifies each directory as a command line argument for the processor.
21. // The Android plugin uses this method to pass the arguments to the
22. // annotation processor.
23. @Override
24. Iterable<String> asArguments() {
25. // Use the form '-Akey[=value]' to pass your options to the Java compiler.
26. ["-AinputDir=${inputDir.singleFile.absolutePath}",
27. "-AoutputDir=${outputDir.absolutePath}"]
28. }
29. }

31. android {...}

在创建实现 CommandLineArgumentProvider 的类后，您需要使用annotationProcessorOptions.compilerArgumentProvider属性初始化并将其传递至 Android 插件，如下所示。

1. // This is in your module's build.gradle file.
2. android {
3. defaultConfig {
4. javaCompileOptions {
5. annotationProcessorOptions {
6. // Creates a new MyArgsProvider object, specifies the input and
7. // output paths for the constructor, and passes the object
8. // to the Android plugin.
9. compilerArgumentProvider new MyArgsProvider(files("input/path"),
10. new File("output/path"))
11. }
12. }
13. }
14. }

如需了解有关实现 CommandLineArgumentProvider 如何帮助提高构建性能的详细信息，请阅读缓存 Java 项目。

停用注解处理器错误检查

如果编译类路径中的依赖项包含您不需要的注解处理器，您可以将以下代码添加到 build.gradle 文件中，停用错误检查。 请记住，您添加到编译类路径中的注解处理器仍不会添加到处理器类路径中。

1. android {
2. ...
3. defaultConfig {
4. ...
5. javaCompileOptions {
6. annotationProcessorOptions {
7. includeCompileClasspath false
8. }
9. }
10. }
11. }

如果您将项目的注解处理器迁移到处理器类路径后遇到问题，可通过将 includeCompileClasspath 设置为 true，允许编译类路径上包含注解处理器。 但是，我们不建议将此属性设置为 true，并且我们将在以后的 Android plugin 更新版本中移除这种操作的相关选项。

排除传递依赖项

随着应用范围的扩大，其中可包含许多依赖项，包括直接依赖项和传递依赖项（应用的导入库所依赖的库）。要排除不再需要的传递依赖项，您可以使用exclude 关键字，如下所示：

1. dependencies {
2. implementation('some-library') {
3. exclude group: 'com.example.imgtools', module: 'native'
4. }
5. }

从测试配置中排除传递依赖项

如果需要从您的测试中排除某些传递依赖项，上文所示的代码示例可能无法按预期发挥作用。 这是因为测试配置（例如 androidTestImplementation）扩展了模块的 implementation 配置。 也就是说，在 Gradle 解析配置时其中始终包含 implementation 依赖项。

因此，要从测试中排除传递依赖项，必须在执行代码时执行此操作，如下所示：

1. android.testVariants.all { variant ->
2. variant.getCompileConfiguration().exclude group: 'com.jakewharton.threetenabp', module: 'threetenabp'
3. variant.getRuntimeConfiguration().exclude group: 'com.jakewharton.threetenabp', module: 'threetenabp'
4. }

注：您仍可在排除依赖项部分的原始代码示例所示的依赖项块中使用 exclude 关键字，以忽略特定于测试配置的传递依赖项，以及其他配置不包含的传递依赖项。

使用 variant-aware 依赖项管理

Android 插件 3.0.0 及更高版本包含一项新的依赖项机制，这种机制可以在消费库时自动匹配不同类型。 也就是说，应用的 debug 不同类型将自动消费库的 debug 不同类型，依此类推。这种机制也适用于使用风格的情况—应用的 freeDebug 变体将使用库的 freeDebug 变体。

要让插件准确匹配变体，您需要为无法直接匹配的情况提供匹配回退。 假设您的应用配置一个名为“staging”的构建类型，但其库依赖项之一没有进行相应配置。 在插件尝试构建您的“staging”版本的应用时，它将无法了解库要使用哪一个版本，您将看到一条类似以下消息的错误消息：

1. Error:Failed to resolve: Could not resolve project :mylibrary.
2. Required by:
3. project :app

解决与变体匹配相关的构建错误

插件包含 DSL 元素，这些元素有助于控制 Gradle 应如何解决应用与依赖项之间无法实现直接变体匹配的情况。 请通过查阅下表来确定应使用哪个 DSL 属性来解决与 variant-aware 依赖项匹配相关的特定构建错误。

配置 Wear OS 应用依赖项

配置 Wear OS 模块的依赖项与配置任何其他模块的依赖项相似。 也就是说，它们使用的依赖项配置相同，比如 implementation 和 compileOnly。

Wear 模块还支持 variant-aware 依赖项管理。因此，如果应用基础模块的依赖项位于 Wear 模块上，则基础模块的每个变体都会使用 Wear 模块中匹配的变体。如果构建依赖项仅在一个 Wear 模块上的简单应用，而且此模块配置的变体与基础模块相同，则需要在基础模块的 build.gradle 文件中指定 wearApp 配置，如下所示：

1. dependencies {
2. // If the main and Wear app modules have the same variants,
3. // variant-aware dependency management automatically matches
4. // variants of the main app module with that of the wear module.
5. wearApp project(':wearable')
6. }

如果有多个 Wear 模块，并且您想要按应用风格指定不同的 Wear 模块，则可使用 flavorWearApp配置执行此操作，如下所示（但不能包含其他使用 wearApp 配置的依赖项）：

1. dependencies {
2. paidWearApp project(':wear1')
3. demoWearApp project(':wear1')
4. freeWearApp project(':wear2')
5. }

远程代码库

如果您的依赖项并非本地库或文件树，Gradle 会在您的 build.gradle 文件 repositories 程序块中指定的任何一个在线代码库中寻找文件。 列出各代码库的顺序决定了 Gradle 在这些代码库中搜索各项目依赖项的顺序。 例如，如果代码库 A 和 B 都提供某依赖项，而您先列出代码库 A，则 Gradle 会从代码库 A 下载此依赖项。

默认情况下，Android Studio 新项目会在项目的顶级 build.gradle 文件中指定Google 的 Maven 代码库和 JCenter 作为代码库位置，如下所示：

1. allprojects {
2. repositories {
3. google()
4. jcenter()
5. }
6. }

如果您需要的内容来自 Maven 中央代码库，则添加mavenCentral()；如果来自本地代码库，则使用 mavenLocal()：

1. allprojects {
2. repositories {
3. google()
4. jcenter()
5. mavenCentral()
6. mavenLocal()
7. }
8. }

或者，也可像下面这样声明特定 Maven 或 Ivy 代码库：

1. allprojects {
2. repositories {
3. maven {
4. url "https://repo.example.com/maven2"
5. }
6. maven {
7. url "file://local/repo/"
8. }
9. ivy {
10. url "https://repo.example.com/ivy"
11. }
12. }
13. }

如需了解详细信息，请参阅Gradle 代码库指南。

Google 的 Maven 代码库

Google 的 Maven 代码库中提供了下列 Android 库的最新版本：

• Android 支持库
• 架构组件库
• 约束布局库
• AndroidX Test
• 数据绑定库
• Android 即搜即得库
• Wear OS
• Google Play 服务
• Firebase 您可以在 Google 的 Maven 代码库索引查看所有可用的项目（请参阅下文有关编程式访问的内容）。

要将其中一个库添加到您的构建，请在您的顶级 build.gradle 文件中加入 Google 的 Maven 代码库：

1. allprojects {
2. repositories {
3. google()

5. // If you're using a version of Gradle lower than 4.1, you must instead use:
6. // maven {
7. //     url 'https://maven.google.com'
8. // }
9. // An alternative URL is 'https://dl.google.com/dl/android/maven2/'
10. }
11. }

然后将所需库添加到您的模块的 dependencies 程序块。例如，appcompat 库如下所示：

1. dependencies {
2. implementation 'com.android.support:appcompat-v7:28.0.0'
3. }

但如果您尝试使用以上库的旧版本时依赖项失败，则表明 Maven 代码库中未提供该版本，您必须改为从离线代码库获取该库。

编程式访问

如需编程式访问 Google 的 Maven 项目，您可以从 maven.google.com/master-index.xml 获取项目组的 XML 列表。然后，对于任何组，您都可以在以下位置查看其库名称和版本：

maven.google.com/_group_path/group-index.xml_

例如，android.arch.lifecycle 组中的库列于 maven.google.com/android/arch/lifecycle/group-index.xml 中。

您还可以在以下位置下载 POM 和 JAR 文件：

maven.google.com/_group_path/library/version/library-version.ext_

例如：maven.google.com/android/arch/lifecycle/compiler/1.0.0/compiler-1.0.0.pom。

来自 SDK 管理器的离线代码库

对于 Google Maven 代码库中未提供的库（通常是旧版本库），您必须从 SDK 管理器下载离线 Google 代码库软件包。

然后您就可以照常将这些库添加到您的 dependencies 程序块。

离线库保存在 android_sdk/extras/ 中。

依赖项顺序

您列出依赖项的顺序表示各依赖项的优先级：第一个库的优先级高于第二个，第二个的优先级高于第三个，依此类推。 从库合并资源或合并 manifest 元素到您的应用中时，此顺序具有重要意义。

例如，如果您的项目声明以下内容：

• 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。

如需了解有关如何合并不同项目源/依赖项 manifest 的详细信息，请参阅合并多个 manifest 文件。

查看依赖项树

某些直接依赖项可能会有其自己的依赖项。 这些依赖项称为传递依赖项。 Gradle 将会自动为您收集并添加这些传递依赖项，无需您手动逐一加以声明。 为直观地呈现您的项目的直接和传递依赖项，Android Plugin for Gradle 提供了一项 Gradle 任务，可为每个构建不同类型和测试源集生成依赖项树。

要运行该任务，请执行如下操作：

• 选择 View > Tool Windows > Gradle（或点击工具窗口栏中的 Gradle）。
• 展开 AppName > Tasks > android 并双击 androidDependencies。 Gradle 执行任务后，Run 窗口应随即打开以显示输出。 以下示例输出显示了调试构建不同类型的依赖项树，并包含前一示例中的本地库模块依赖项和远程依赖项。

1. Executing tasks: [androidDependencies]
2. :app:androidDependencies
3. debug
4. /**
5. * Both the library module dependency and remote binary dependency are listed
6. * with their transitive dependencies.
7. */
8. +--- MyApp:mylibrary:unspecified
9. |    \--- com.android.support:appcompat-v7:28.0.0
10. |         +--- com.android.support:animated-vector-drawable:28.0.0
11. |         |    \--- com.android.support:support-vector-drawable:28.0.0
12. |         |         \--- com.android.support:support-v4:28.0.0
13. |         |              \--- LOCAL: internal_impl-28.0.0.jar
14. |         +--- com.android.support:support-v4:28.0.0
15. |         |    \--- LOCAL: internal_impl-28.0.0.jar
16. |         \--- com.android.support:support-vector-drawable:28.0.0
17. |              \--- com.android.support:support-v4:28.0.0
18. |                   \--- LOCAL: internal_impl-28.0.0.jar
19. \--- com.android.support:appcompat-v7:28.0.0
20. +--- com.android.support:animated-vector-drawable:28.0.0
21. |    \--- com.android.support:support-vector-drawable:28.0.0
22. |         \--- com.android.support:support-v4:28.0.0
23. |              \--- LOCAL: internal_impl-28.0.0.jar
24. +--- com.android.support:support-v4:28.0.0
25. |    \--- LOCAL: internal_impl-28.0.0.jar
26. \--- com.android.support:support-vector-drawable:28.0.0
27. \--- com.android.support:support-v4:28.0.0
28. \--- LOCAL: internal_impl-28.0.0.jar
29. ...

如需了解在 Gradle 中管理依赖项的详细信息，请参阅《Gradle 用户指南》中的依赖项管理基础知识。

修复依赖项解析错误

在向应用项目添加多个依赖项时，这些直接和传递依赖项可能会彼此冲突。 Android Gradle Plugin 会尝试妥善解决这些冲突问题，但某些冲突可能会导致编译时间或运行时错误。

为帮助您调查是哪些依赖项导致错误，请检查您的应用的依赖项树并寻找多次出现的依赖项或版本冲突的依赖项。

如果无法轻易确定重复的依赖项，请按以下步骤尝试使用 Android Studio 的界面搜索包含重复类的依赖项：

• 选择菜单栏中的 Navigate > Class。
• 在弹出式搜索对话框中，确保 Include non-project items 旁的方框已勾选。
• 键入出现在构建错误中的类的名称。
• 检查包括该类的依赖项的结果。 以下部分介绍您可能遇到的不同类型的依赖项解析错误及其修复方法。

修复重复类错误

如果某类多次出现在运行时类路径中，您会收到一条与以下内容相似的错误：

1. Program type already present com.example.MyClass

该错误通常是下列其中一种情况所致：

• 二进制文件依赖项包括您的应用同时作为直接依赖项包括的库。例如，您的应用在库 A 和库 B 上声明了直接依赖项，但库 A 的二进制文件中已包括库 B。
• 要解决此问题，请取消将库 B 作为直接依赖项。
• 您的应用在同一库上具有本地二进制文件依赖项和远程二进制文件依赖项。
• 要解决此问题，请移除其中一个二进制文件依赖项。

解决类路径之间的冲突问题

当 Gradle 解析编译类路径时，会先解析运行时类路径，然后使用此结果确定应添加到编译类路径的依赖项版本。 换言之，运行时类路径决定下游类路径的相同依赖项所需的版本号。

应用的运行时类路径还决定 Gradle 匹配运行类路径中应用测试 APK 的依赖项所需要的版本号。 图 1 介绍类路径的层级。

图 1. 必须根据此层级匹配出现在多个类路径中的依赖项版本号。

如果相同依赖项的冲突版本出现在多个类路径中，您可能会看到与以下内容相似的错误：

1. Conflict with dependency 'com.example.library:some-lib:2.0' in project 'my-library'.
2. Resolved versions for runtime classpath (1.0) and compile classpath (2.0) differ.

例如，当您的应用使用 implementation依赖项配置加入某依赖项版本，并且库模块使用runtimeOnly 配置加入此依赖项的不同版本时，可能会发生该冲突。 要解决此问题，请执行以下其中一项操作：

• 将所需版本的依赖项作为 api 依赖项加入您的库模块。也就是说，仅库模块声明此依赖项，但应用模块也可间接访问其 API。
• 或者，您也可以同时在两个模块中声明此依赖项，但应确保每个模块使用的版本相同。请考虑配置项目范围的属性，以确保各依赖项的多个版本在整个项目中都保持一致。

应用自定义构建逻辑

本节介绍的高级主题在您想要扩展 Android Gradle Plugin 或编写自己的插件时很有用。

为自定义逻辑发布变体依赖项

库可以包含其他项目或子项目可能要使用的功能。 发布库是为其消费者提供库的流程。 库可以控制其消费者在编译时和运行时可访问的依赖项。

现有两种不同的配置，其中包含消费者为使用库而必须使用的各类路径的传递依赖项，如下所述：

• variant_nameApiElements：此配置包含编译时消费者可使用的传递依赖项。
• variant_nameRuntimeElements：此配置包含运行时消费者可使用的传递依赖项。 如需了解有关不同配置之间关系的详细信息，请转到 Java 库插件配置。

自定义依赖项解析策略

项目包含的依赖项可能包含在相同库的两个不同版本中，这样会导致依赖项冲突。例如，如果您的项目依赖于模块 A 的版本 1 和模块 B 的版本 2，模块 A 间接依赖于模块 B 的版本 3，则会出现依赖项版本冲突。

要解决此冲突问题，Android Gradle Plugin 需使用以下依赖项解析策略：当插件检测到依赖图中包含相同模块的不同版本时，会默认选择版本最高的模块。

但此策略可能无法按预期发挥作用。 要自定义依赖项解析策略，请使用以下配置解析您任务所需变体的特定依赖项：

• variant_nameCompileClasspath：此配置包含适用于给定变体编译类路径的解析策略。
• variant_nameRuntimeClasspath：此配置包含适用于给定变体运行时类路径的解析策略。 Android Gradle Plugin 包含可用于访问各变体配置对象的 getter。 因此，您可以使用变体 API 查询依赖项解析策略，如下例所示：

1. android {
2. applicationVariants.all { variant ->
3. // Return compile configuration objects of a variant.
4. variant.getCompileConfiguration().resolutionStrategy {
5. // Use Gradle's ResolutionStrategy API
6. // to customize how this variant resolves dependencies.
7. ...
8. }
9. // Return runtime configuration objects of a variant.
10. variant.getRuntimeConfiguration().resolutionStrategy {
11. ...
12. }
13. // Return annotation processor configuration of a variant.
14. variant.getAnnotationProcessorConfiguration().resolutionStrategy {
15. ...
16. }
17. }
18. }