添加构建依赖项

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 将库系列及其版本组合在一起。您可以在版本目录和构建文件中包含 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 会在版本目录文件和 Project Structure Dialog 中显示来自 Google Play SDK Index 中公共 SDK 的 lint 警告：

• SDK 已被其作者标记为过时。
• SDK 违反 Play 政策。
• SDK 存在已知的安全漏洞。
• SDK 已被其作者弃用。

这些警告提示您应更新这些依赖项，因为使用过时的版本可能会导致将来无法发布到 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'
}