添加 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 脚本下）：

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

   别名可以包含短划线或下划线。这些别名会生成您可以在 build 脚本中引用的嵌套值。引用以目录的名称（即 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) 中找到，该清单会对库系列及其版本进行分组。您可以在版本目录和 build 文件中添加 BoM，并让它为您管理这些版本。如需了解详情，请参阅使用物料清单。

3. 将对依赖项别名的引用添加到需要该依赖项的模块的 build 脚本中。从 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 限定符，因此您无法在库别名的开头使用 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')
}

为特定 build 变体配置依赖项

上述所有配置都会将依赖项应用于所有 build 变体。如果您只想为特定的构建变体源代码集或测试源代码集声明依赖项，则必须将配置名称的首字母大写，并在其前面加上构建变体或测试源代码集的名称作为前缀。

例如，如需使用 implementation 配置仅向“free”产品变种添加远程二进制文件依赖项，请使用以下代码：

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

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

不过，如果您想为将产品变种和 build 类型组合在一起的变体添加依赖项，则必须初始化配置名称：

// 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 会在版本目录文件和 Project Structure 对话框中针对 Google Play SDK 索引中的公共 SDK 显示 lint 警告：

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

这些警告表示您应更新这些依赖项，因为如果继续使用过时的版本，您日后可能会无法将内容发布到 Google Play 管理中心。

在不使用版本目录的情况下添加 build 依赖项

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

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

此 build 文件声明了对“com.example.android”命名空间组内的 12.3 版“app-magic”库的依赖关系。远程二进制文件依赖项声明是以下内容的简写形式：

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

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 中使用该版本。通常，根 build 脚本除了此 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
}

如果您有一个单模块项目，则可以在模块级 build 脚本中明确指定版本，并将项目级 build 脚本留空：

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

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