添加构建依赖项

Android Studio 中的 Gradle 构建系统允许您将外部二进制文件或其他库模块作为依赖项包含到您的构建中。这些依赖项可以位于您的机器上或远程存储库中，并且它们声明的任何传递依赖项也会自动包含在内。本页面介绍了如何在您的 Android 项目中使用依赖项，包括有关 Android Gradle 插件 (AGP) 特定的行为和配置的详细信息。有关 Gradle 依赖项的更深入的概念指南，您还应该参考 Gradle 依赖项管理指南 - 但请记住，您的 Android 项目必须仅使用本页面上定义的 依赖项配置。

添加库或插件依赖项

添加和管理构建依赖项的最佳方法是使用版本目录，这是新项目默认使用的方法。本节介绍了用于 Android 项目的最常见的配置类型；有关更多选项，请参考 Gradle 文档。有关使用版本目录的应用程序示例，请参见 Now in Android。如果您已经设置了没有版本目录的构建依赖项，并且拥有一个多模块项目，我们建议您 迁移。

有关添加和管理原生依赖项（不常见）的指南，请参见 原生依赖项。

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

1. 在版本目录文件中添加要使用的依赖项版本的别名，名为 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"。

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，并让它为您管理这些版本。有关详细信息，请参阅 使用物料清单。

3. 在需要依赖项的模块的构建脚本中添加对依赖项别名的引用。从构建脚本中引用别名时，将别名的下划线和连字符转换为点。我们的模块级构建脚本如下所示

   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 项目中用于依赖项的每种配置。

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"))
}

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')
}

为特定构建变体配置依赖项

所有上述配置都将依赖项应用于所有构建变体。如果您希望仅针对特定 构建变体 源集或 测试源集 声明依赖项，则必须大写配置名称并在其前面加上构建变体或测试源集的名称。

例如，要仅使用 implementation 配置将远程二进制依赖项添加到您的“免费”产品风格，请使用以下命令

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

但是，如果您要添加针对将产品风格和构建类型组合在一起的变体的依赖项，则必须初始化配置名称

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

要为您的本地测试和仪器测试添加 implementation 依赖项，它看起来像这样

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")
}

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

那么，扁平依赖项顺序如下

1. LIB_A
2. LIB_D
3. LIB_B
4. 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 的 lint 警告，当以下问题适用时

• SDK 由其作者标记为已过时。
• SDK 违反了 Play 政策。

这些警告是信号，表明您应该更新这些依赖项，因为使用过时的版本可能会阻止您将来发布到 Google Play 管理中心。

在没有版本目录的情况下添加构建依赖项

我们建议使用版本目录来添加和管理依赖项，但简单的项目可能不需要它们。以下是一个不使用版本目录的构建文件的示例

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"))
}

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 版本的依赖关系。远程二进制依赖关系声明是以下内容的简写

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

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 块外，根构建脚本是空的。

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

如果只有一个模块的项目，则可以在模块级构建脚本中显式指定版本，并将项目级构建脚本保留为空。

plugins {
    id("com.android.application") version "8.3.0"
}

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}