添加 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 Scripts 目录下）：

   [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) 中提供，该清单对库系列及其版本进行了分组。您可以在版本目录和 build 文件中添加 BoM，让它为您管理这些版本。如需了解详情，请参阅使用物料清单。

3. 在需要相应依赖项的模块的 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 变体。如果您只想为特定的 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.5.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.5.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 政策。

这些警告表示您应该更新这些依赖项，因为使用过时的版本可能会导致您日后无法发布到 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”命名空间组内声明了对“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: 定义的库名称一致。在构建应用时，构建系统会编译库模块，并将生成的编译内容打包到应用中。

build 文件还声明了对 Android Gradle 插件 (com.application.android) 的依赖项。如果您有多个模块使用同一个插件，则所有模块中的 build 类路径上只能有一个插件版本。您应该将插件依赖项与版本一起添加到根 build 脚本中，并指明不应用该插件，而不是在每个模块构建脚本中指定版本。添加 apply false 会告知 Gradle 记下该插件的版本，但不要在根 build 中使用该版本。通常，除了此 plugins 代码块之外，根 build 脚本是空的。

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