配置 build

Android 构建系统会编译应用资源和源代码,然后将它们打包成 APK 或 Android App Bundle 文件,供您测试、部署、签名和分发。

Android Studio 使用高级构建工具包 Gradle 来自动执行和管理构建流程,同时也允许您自行指定灵活的 build 配置。每项 build 配置均可定义各自的一组代码和资源,同时重复利用所有应用版本共用的部分。Android Gradle 插件与该构建工具包搭配使用,提供专用于构建和测试 Android 应用的流程和可配置设置。

Gradle 和 Android Gradle 插件独立于 Android Studio 运行。这意味着,您可以在 Android Studio 内、计算机上的命令行或未安装 Android Studio 的计算机(如持续集成服务器)上构建 Android 应用。

如果您不使用 Android Studio,可以学习如何从命令行构建和运行应用。无论您是从命令行、在远程计算机上还是使用 Android Studio 构建项目,构建过程的输出都相同。

注意:由于 Gradle 和 Android Gradle 插件独立于 Android Studio 运行,因此您需要单独更新构建工具。请阅读版本说明,了解如何更新 Gradle 和 Android Gradle 插件

Android 构建系统非常灵活,让您可以在不修改应用核心源代码文件的情况下创建自定义的 build 配置。本页介绍了 Android 构建系统的工作原理,以及它如何帮助您对多项 build 配置进行自定义和自动化处理。如需详细了解如何部署应用,请参阅构建和运行应用。如要立即开始使用 Android Studio 创建自定义 build 配置,请参阅配置 build 变体

构建流程

构建流程涉及许多将项目转换成 Android 应用软件包 (APK) 或 Android App Bundle (AAB) 文件的工具和流程。

Android Gradle 插件可以为您完成构建流程的大部分工作,但了解构建流程的某些方面会很有用,有助于您根据需要调整 build。

不同的项目可能具有不同的构建目标。例如,针对第三方库的 build 会生成 Android ARchive (AAR) 或 Java Archive (JAR) 库。 不过,应用是最常见的项目类型,而应用项目的 build 会生成应用的调试版或者发布版 APK 或 AAB,以用于部署、测试或向外部用户发布。

本页重点介绍应用开发,但许多 build 步骤和概念对大多数 build 类型来说都是通用的。

Android build 术语表

Gradle 和 Android Gradle 插件可帮助您完成 build 以下方面的配置:

build 类型

build 类型定义 Gradle 在构建和打包应用时使用的某些属性。通常针对开发生命周期的不同阶段进行配置。

例如,调试 build 类型会启用调试选项,并会使用调试密钥为应用签名;而发布 build 类型则可能会缩减应用大小、对应用进行混淆处理,并使用发布密钥为应用签名以进行分发。

如要构建应用,您必须至少定义一个 build 类型。Android Studio 默认会创建调试 build 类型和发布 build 类型。如要着手为应用自定义打包设置,不妨了解如何配置 build 类型

产品变种
产品变种代表您可以向用户发布的不同应用版本,如应用的免费版和付费版。您可以自定义产品变种以使用不同的代码和资源,同时共享并重用所有应用版本共用的部分。产品变种是可选的,您必须手动创建。如要开始创建应用的不同版本,请了解如何配置产品变种
build 变体
build 变体是 build 类型与产品变种的交叉产物,也是 Gradle 用来构建应用的配置。利用 build 变体,您可以在开发期间构建产品变种的调试版本,以及构建产品变种的已签名发布版本以供分发。虽然您无法直接配置 build 变体,但可以配置构成 build 变体的 build 类型和产品变种。创建额外的 build 类型或产品变种也会产生额外的 build 变体。如需了解如何创建和管理 build 变体,请参阅配置 build 变体概览。
清单条目
您可以在 build 变体配置中为清单文件的某些属性指定值。这些 build 值会覆盖清单文件中的现有值。如果您要为应用生成多个变体,让每一个变体都具有不同的应用名称、最低 SDK 版本或目标 SDK 版本,便可运用这一技巧。当存在多个清单时,清单合并工具会合并清单设置
依赖项
构建系统会管理来自本地文件系统以及来自远程仓库的项目依赖项。这样一来,您就不必手动搜索、下载依赖项的二进制文件包以及将它们复制到项目目录中。如需了解详情,请参阅添加 build 依赖项
签名
构建系统既允许您在 build 配置中指定签名设置,也可以在构建流程中自动为应用签名。构建系统通过已知凭据使用默认密钥和证书为调试版本签名,以避免在构建时提示输入密码。除非您为此 build 明确定义签名配置,否则,构建系统不会为发布版本签名。如果您没有发布密钥,可以按为应用签名中所述生成一个。通过大多数应用商店分发应用时都需要使用已签名的发布 build。
代码和资源缩减
构建系统允许您为每个 build 变体指定不同的 ProGuard 规则文件。在构建应用时,构建系统会应用一组适当的规则以使用其内置的缩减工具(如 R8)缩减您的代码和资源。 缩减代码和资源有助于缩减 APK 或 AAB 大小。
多 APK 支持
通过构建系统可以自动构建不同的 APK,并让每个 APK 只包含特定屏幕密度或应用二进制接口 (ABI) 所需的代码和资源。如需了解详情,请参阅构建多个 APK。不过,我们建议的方法是发布单个 AAB,因为它除了让您可以按屏幕密度和 ABI 进行拆分以外,还可以让您按语言进行拆分,同时无需将多个工件上传到 Google Play。2021 年 8 月之后提交的所有新应用都必须使用 AAB。

Android build 中的 Java 版本

无论您的源代码是使用 Java 和/或 Kotlin 编写的,都必须在多个地方为您的 build 选择 JDK 或 Java 语言版本。如需了解详情,请参阅 Android build 中的 Java 版本

build 配置文件

如果您创建自定义 build 配置,就需要对一个或多个 build 配置文件做出更改。这些纯文本文件使用领域特定语言 (DSL) 使用 Kotlin 脚本(Kotlin 语言的一种形式)描述和操纵构建逻辑。您还可以使用 Java 虚拟机 (JVM) 的动态语言 Groovy 来配置构建。

您无需了解 Kotlin 脚本或 Groovy 便可开始配置 build,因为 Android Gradle 插件引入了您需要的大多数 DSL 元素。如需详细了解 Android Gradle 插件 DSL,请参阅 DSL 参考文档。 Kotlin 脚本还依赖于底层 Gradle Kotlin DSL

开始新项目时,Android Studio 会自动为您创建其中的部分文件,并为其填充合理的默认值。项目文件结构具有以下布局:

└── MyApp/  # Project
    ├── gradle/
    │   └── wrapper/
    │       └── gradle-wrapper.properties
    ├── build.gradle(.kts)
    ├── settings.gradle(.kts)
    └── app/  # Module
        ├── build.gradle(.kts)
        └── build/
            ├── libs/
            └── src/
                └── main/  # Source set
                    ├── java/
                    │   └── com.example.myapp
                    ├── res/
                    │   ├── drawable/
                    │   ├── values/
                    │   └── ...
                    └── AndroidManifest.xml

有一些 Gradle build 配置文件是 Android 应用的标准项目结构的组成部分。您必须了解其中每个文件的范围和用途及其定义的基础 DSL 元素,才能着手配置 build。

Gradle 封装容器文件

Gradle 封装容器 (gradlew) 是源代码中包含的一个小应用,用于下载和启动 Gradle 本身。这样可以创建更加一致的构建执行。开发者下载应用源代码并运行 gradlew。这将下载所需的 Gradle 发行版,并启动 Gradle 来构建您的应用。

gradle/wrapper/gradle-wrapper.properties 文件包含一个属性 distributionUrl,该属性描述了用于运行 build 的 Gradle 版本。

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Gradle 设置文件

settings.gradle.kts 文件(对于 Kotlin DSL)或 settings.gradle 文件(对于 Groovy DSL)位于项目的根目录下。此设置文件会定义项目级代码库设置,并告知 Gradle 在构建应用时应将哪些模块包含在内。多模块项目需要指定应包含在最终 build 中的每个模块。

对于大多数项目,该文件默认如下所示:

Kotlin

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. The code below
      * defines the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
      google()
      mavenCentral()
  }
}
rootProject.name = "My Application"
include(":app")

Groovy

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. The code below
      * defines the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "My Application"
include ':app'

顶层 build 文件

顶层 build.gradle.kts 文件(对于 Kotlin DSL)或 build.gradle 文件(对于 Groovy DSL)位于项目的根目录下。它通常定义了项目中的模块所使用的插件通用版本。

以下代码示例说明了创建新项目后,顶层 build 脚本中的默认设置和 DSL 元素:

Kotlin

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id("com.android.application") version "8.2.2" apply false
    id("com.android.library") version "8.2.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.20" apply false
}

Groovy

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id 'com.android.application' version '8.2.2' apply false
    id 'com.android.library' version '8.2.2' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.20' apply false
}