添加构建依赖项

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

添加库或插件依赖项

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

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

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

1. 在版本目录文件（称为 libs.versions.toml，位于 项目 视图中的 gradle 目录或 Android 视图中的 Gradle 脚本 下）的 [versions] 部分中添加要使用的依赖项版本的别名。

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   别名可以包含连字符或下划线。这些别名会生成可以在构建脚本中引用的嵌套值。引用从目录的名称开始，即 libs.versions.toml 中的 libs 部分。当使用单个版本目录时，我们建议保留“libs”的默认值。

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

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 配置将远程二进制依赖项添加到您的“free”产品风味中，请使用以下方法

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 Console 的依赖项信息

在构建您的应用程序时，AGP 包含描述编译到您的应用程序中的库依赖项的元数据。在上传您的应用程序时，Play Console 会检查此元数据以提供有关应用程序使用的 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 Console。

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

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

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