配置您的构建

Android 构建系统会编译应用资源和源代码，并将它们打包成 APK 或 Android 应用捆绑包，您可以测试、部署、签名和分发这些捆绑包。

在 Gradle 构建概述 和 Android 构建结构 中，我们讨论了构建概念和 Android 应用的结构。现在该配置构建了。

Android 构建词汇表

Gradle 和 Android Gradle 插件可帮助您配置构建的以下方面

构建类型

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

例如，调试构建类型会启用调试选项，并使用调试密钥对应用进行签名，而发布构建类型可能会缩减、混淆和使用发布密钥对应用进行签名，以便进行分发。

您必须定义至少一个构建类型才能构建应用。Android Studio 默认情况下会创建调试和发布构建类型。要开始自定义应用的打包设置，请了解如何 配置构建类型。

产品风格
产品风格代表您可以发布给用户的应用的不同版本，例如免费版本和付费版本。您可以自定义产品风格以使用不同的代码和资源，同时共享和重用对应用的所有版本都通用的部分。产品风格是可选的，您必须手动创建它们。要开始创建应用的不同版本，请了解如何 配置产品风格。
构建变体
构建变体是构建类型和产品风格的交叉产品，是 Gradle 用于构建应用的配置。使用构建变体，您可以在开发期间构建产品风格的调试版本，并构建产品风格的已签名发布版本，以便进行分发。虽然您不会直接配置构建变体，但您会配置形成它们的构建类型和产品风格。创建额外的构建类型或产品风格还会创建额外的构建变体。要了解如何创建和管理构建变体，请阅读 配置构建变体 概述。
清单条目
您可以在构建变体配置中指定清单文件某些属性的值。这些构建值会覆盖清单文件中现有的值。如果您想要生成具有不同应用名称、最小 SDK 版本或目标 SDK 版本的应用的多个变体，这将很有用。当存在多个清单文件时，清单合并工具会 合并清单设置。
依赖项
构建系统会管理来自本地文件系统和远程存储库的项目依赖项。这意味着您不必手动搜索、下载和将依赖项的二进制包复制到您的项目目录中。要了解更多信息，请参阅 添加构建依赖项。
签名
构建系统允许您在构建配置中指定签名设置，并且它可以在构建过程中自动签署您的应用。构建系统使用已知凭据使用默认密钥和证书签署调试版本，以避免在构建时出现密码提示。除非您为此次构建明确定义签名配置，否则构建系统不会签署发布版本。如果您没有发布密钥，则可以按照签署您的应用中所述生成一个。签署的发布构建是通过大多数应用商店分发应用所必需的。
代码和资源缩减
构建系统允许您为每个构建变体指定不同的 ProGuard 规则文件。构建应用时，构建系统会使用其内置缩减工具（如 R8）将适当的规则集应用于缩减您的代码和资源。缩减代码和资源有助于减小 APK 或 AAB 的大小。
多 APK 支持
构建系统允许您自动构建不同的 APK，每个 APK 只包含特定屏幕密度或应用程序二进制接口 (ABI) 所需的代码和资源。有关更多信息，请参阅构建多个 APK。但是，发布单个 AAB 是推荐的做法，因为它除了屏幕密度和 ABI 之外还提供按语言划分，同时避免了将多个工件上传到 Google Play 的需要。2021 年 8 月之后提交的所有新应用都必须使用 AAB。

Android 构建中的 Java 版本

无论您的源代码是用 Java、Kotlin 还是两者编写，您都必须在几个地方为您的构建选择一个 JDK 或 Java 语言版本。有关详细信息，请参阅Android 构建中的 Java 版本。

构建配置文件

创建自定义构建配置需要您更改一个或多个构建配置文件。这些纯文本文件使用特定于域的语言 (DSL) 来使用Kotlin 脚本描述和操作构建逻辑，Kotlin 脚本是 Kotlin 语言的一种变体。您也可以使用Groovy（一种用于 Java 虚拟机 (JVM) 的动态语言）来配置您的构建。

您不需要了解 Kotlin 脚本或 Groovy 就可以开始配置您的构建，因为 Android Gradle 插件引入了您所需的大多数 DSL 元素。要详细了解 Android Gradle 插件 DSL，请阅读DSL 参考文档。Kotlin 脚本还依赖于底层的Gradle Kotlin DSL

启动新项目时，Android Studio 会自动为您创建其中一些文件，并根据合理的默认值填充这些文件。有关所创建文件的概述，请参阅Android 构建结构。

Gradle Wrapper 文件

Gradle Wrapper (gradlew) 是随您的源代码一起包含的一个小型应用程序，它可以下载并启动 Gradle 本身。这会创建更一致的构建执行。开发人员下载应用程序源代码并运行 gradlew。这将下载所需的 Gradle 分发版，并启动 Gradle 来构建您的应用程序。

gradle/wrapper/gradle-wrapper.properties 文件包含一个属性 distributionUrl，该属性描述用于运行构建的 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 构建应用时应包含哪些模块。多模块项目需要指定应包含在最终构建中的每个模块。

对于大多数项目，该文件默认情况下如下所示

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. Here we
      * define 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. Here we
      * define 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.gradle.kts 文件（用于 Kotlin DSL）或 build.gradle 文件（用于 Groovy DSL）位于根项目目录中。它通常定义项目中模块使用的插件的通用版本。

以下代码示例描述了在创建新项目后顶层构建脚本中的默认设置和 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.6.0" apply false
    id("com.android.library") version "8.6.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.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.6.0' apply false
    id 'com.android.library' version '8.6.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.0.20' apply false
}

模块级构建文件

模块级 build.gradle.kts（用于 Kotlin DSL）或 build.gradle 文件（用于 Groovy DSL）位于每个 project/module/ 目录中。它允许您为其所在的特定模块配置构建设置。配置这些构建设置使您可以提供自定义打包选项（例如其他构建类型和产品风格），并覆盖 main/ 应用清单或顶层构建脚本中的设置。

Android SDK 设置

您的应用程序的模块级构建文件包含指示在编译时、选择平台行为时以及指定应用程序运行的最低版本时使用的 Android SDK 版本的设置。

Overview of SDK specifications in a Gradle build

compileSdk

compileSdk 确定在编译源代码时可用的 Android 和 Java API。要使用最新的 Android 功能，请在编译时使用最新的 Android SDK。

某些 Android 平台 API 可能在较旧的 API 级别不可用。您可以有条件地保护对更新功能的使用，或使用AndroidX 兼容库在较低的 Android API 级别使用更新的功能。

每个 Android SDK 都提供了一组可用于应用程序的 Java API。在我的 Java 或 Kotlin 源代码中可以使用哪些 Java API中的表格显示了基于 Android SDK 版本可用的 Java API 级别。通过反糖化，较新的 Java API 在较早版本的 Android 上得到支持，反糖化必须在您的构建中启用。

如果您的 compileSdk 与当前版本的 Android Studio、AGP 或项目的库依赖项要求冲突，Android Studio 会显示警告。

minSdk

minSdk 指定您希望应用程序支持的最低版本的 Android。设置 minSdk 会限制哪些设备可以安装您的应用程序。

支持较低版本的 Android 可能需要在您的代码中进行更多条件检查，或更多地使用 AndroidX 兼容库。您应该权衡支持较低版本带来的维护成本与仍在使用这些较低版本的用户的百分比。请参阅 Android Studio 中**新建项目向导**中的版本图表以了解当前的版本使用率百分比。

在 Android Studio 中编辑代码或在构建过程中运行检查时，lint 会警告您使用但在 minSdk 中不可用的 API。您应该通过使更新功能成为条件或使用 Appcompat 来实现向后兼容性来解决这些问题。

targetSdk

targetSdk 具有两个用途

  1. 它设置应用程序的运行时行为。
  2. 它证明您已经针对哪个版本的 Android 进行了测试。

如果您在使用比您的 targetSdk 更高版本的 Android 的设备上运行，Android 会在兼容模式下运行您的应用程序，该模式的行为类似于您的 targetSdk 中指示的较低版本。例如，当 API 23 引入运行时权限模型时，并非所有应用程序都已准备好立即采用它。通过将 targetSdk 设置为 22，这些应用程序可以在 API 23 设备上运行而无需使用运行时权限，并且可以使用最新 compileSdk 版本中包含的功能。Google Play 分发政策在目标 API 级别上强制执行其他策略。

targetSdk 的值必须小于或等于 compileSdk 的值。

注意：compileSdk 和 targetSdk 的值不必相同。请牢记以下基本原则

  • compileSdk 使您可以访问新的 API
  • targetSdk 设置应用程序的运行时行为
  • targetSdk 必须小于或等于 compileSdk

示例应用模块构建脚本

此示例 Android 应用模块构建脚本概述了一些基本 DSL 元素和设置

Kotlin

/**
 * The first section in the build configuration applies the Android Gradle plugin
 * to this build and makes the android block available to specify
 * Android-specific build options.
 */

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

/**
 * Locate (and possibly download) a JDK used to build your kotlin
 * source code. This also acts as a default for sourceCompatibility,
 * targetCompatibility and jvmTarget. Note that this does not affect which JDK
 * is used to run the Gradle build itself, and does not need to take into
 * account the JDK version required by Gradle plugins (such as the
 * Android Gradle Plugin)
 */
kotlin {
    jvmToolchain(11)
}

/**
 * The android block is where you configure all your Android-specific
 * build options.
 */

android {

    /**
     * The app's namespace. Used primarily to access app resources.
     */

    namespace = "com.example.myapp"

    /**
     * compileSdk specifies the Android API level Gradle should use to
     * compile your app. This means your app can use the API features included in
     * this API level and lower.
     */

    compileSdk = 33

    /**
     * The defaultConfig block encapsulates default settings and entries for all
     * build variants and can override some attributes in main/AndroidManifest.xml
     * dynamically from the build system. You can configure product flavors to override
     * these values for different versions of your app.
     */

    defaultConfig {

        // Uniquely identifies the package for publishing.
        applicationId = "com.example.myapp"

        // Defines the minimum API level required to run the app.
        minSdk = 21

        // Specifies the API level used to test the app.
        targetSdk = 33

        // Defines the version number of your app.
        versionCode = 1

        // Defines a user-friendly version name for your app.
        versionName = "1.0"
    }

    /**
     * The buildTypes block is where you can configure multiple build types.
     * By default, the build system defines two build types: debug and release. The
     * debug build type is not explicitly shown in the default build configuration,
     * but it includes debugging tools and is signed with the debug key. The release
     * build type applies ProGuard settings and is not signed by default.
     */

    buildTypes {

        /**
         * By default, Android Studio configures the release build type to enable code
         * shrinking, using minifyEnabled, and specifies the default ProGuard rules file.
         */

        getByName("release") {
            isMinifyEnabled = true // Enables code shrinking for the release build type.
            proguardFiles(
                getDefaultProguardFile("proguard-android.txt"),
                "proguard-rules.pro"
            )
        }
    }

    /**
     * The productFlavors block is where you can configure multiple product flavors.
     * This lets you create different versions of your app that can
     * override the defaultConfig block with their own settings. Product flavors
     * are optional, and the build system does not create them by default.
     *
     * This example creates a free and paid product flavor. Each product flavor
     * then specifies its own application ID, so that they can exist on the Google
     * Play Store or an Android device simultaneously.
     *
     * If you declare product flavors, you must also declare flavor dimensions
     * and assign each flavor to a flavor dimension.
     */

    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            dimension = "tier"
            applicationId = "com.example.myapp.free"
        }

        create("paid") {
            dimension = "tier"
            applicationId = "com.example.myapp.paid"
        }
    }

    /**
     * To override source and target compatibility (if different from the
     * toolchain JDK version), add the following. All of these
     * default to the same value as kotlin.jvmToolchain. If you're using the
     * same version for these values and kotlin.jvmToolchain, you can
     * remove these blocks.
     */
    //compileOptions {
    //    sourceCompatibility = JavaVersion.VERSION_11
    //    targetCompatibility = JavaVersion.VERSION_11
    //}
    //kotlinOptions {
    //    jvmTarget = "11"
    //}
}

/**
 * The dependencies block in the module-level build configuration file
 * specifies dependencies required to build only the module itself.
 * To learn more, go to Add build dependencies.
 */

dependencies {
    implementation(project(":lib"))
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))
}

Groovy

/**
 * The first line in the build configuration applies the Android Gradle plugin
 * to this build and makes the android block available to specify
 * Android-specific build options.
 */

plugins {
    id 'com.android.application'
}

/**
 * Locate (and possibly download) a JDK used to build your kotlin
 * source code. This also acts as a default for sourceCompatibility,
 * targetCompatibility and jvmTarget. Note that this does not affect which JDK
 * is used to run the Gradle build itself, and does not need to take into
 * account the JDK version required by Gradle plugins (such as the
 * Android Gradle Plugin)
 */
kotlin {
    jvmToolchain 11
}

/**
 * The android block is where you configure all your Android-specific
 * build options.
 */

android {

    /**
     * The app's namespace. Used primarily to access app resources.
     */

    namespace 'com.example.myapp'

    /**
     * compileSdk specifies the Android API level Gradle should use to
     * compile your app. This means your app can use the API features included in
     * this API level and lower.
     */

    compileSdk 33

    /**
     * The defaultConfig block encapsulates default settings and entries for all
     * build variants and can override some attributes in main/AndroidManifest.xml
     * dynamically from the build system. You can configure product flavors to override
     * these values for different versions of your app.
     */

    defaultConfig {

        // Uniquely identifies the package for publishing.
        applicationId 'com.example.myapp'

        // Defines the minimum API level required to run the app.
        minSdk 21

        // Specifies the API level used to test the app.
        targetSdk 33

        // Defines the version number of your app.
        versionCode 1

        // Defines a user-friendly version name for your app.
        versionName "1.0"
    }

    /**
     * The buildTypes block is where you can configure multiple build types.
     * By default, the build system defines two build types: debug and release. The
     * debug build type is not explicitly shown in the default build configuration,
     * but it includes debugging tools and is signed with the debug key. The release
     * build type applies ProGuard settings and is not signed by default.
     */

    buildTypes {

        /**
         * By default, Android Studio configures the release build type to enable code
         * shrinking, using minifyEnabled, and specifies the default ProGuard rules file.
         */

        release {
              minifyEnabled true // Enables code shrinking for the release build type.
              proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }

    /**
     * The productFlavors block is where you can configure multiple product flavors.
     * This lets you create different versions of your app that can
     * override the defaultConfig block with their own settings. Product flavors
     * are optional, and the build system does not create them by default.
     *
     * This example creates a free and paid product flavor. Each product flavor
     * then specifies its own application ID, so that they can exist on the Google
     * Play Store or an Android device simultaneously.
     *
     * If you declare product flavors, you must also declare flavor dimensions
     * and assign each flavor to a flavor dimension.
     */

    flavorDimensions "tier"
    productFlavors {
        free {
            dimension "tier"
            applicationId 'com.example.myapp.free'
        }

        paid {
            dimension "tier"
            applicationId 'com.example.myapp.paid'
        }
    }

    /**
     * To override source and target compatibility (if different from the
     * tool chain JDK version), add the following. All of these
     * default to the same value as kotlin.jvmToolchain. If you're using the
     * same version for these values and kotlin.jvmToolchain, you can
     * remove these blocks.
     */
    //compileOptions {
    //    sourceCompatibility JavaVersion.VERSION_11
    //    targetCompatibility JavaVersion.VERSION_11
    //}
    //kotlinOptions {
    //    jvmTarget = '11'
    //}
}

/**
 * The dependencies block in the module-level build configuration file
 * specifies dependencies required to build only the module itself.
 * To learn more, go to Add build dependencies.
 */

dependencies {
    implementation project(":lib")
    implementation 'androidx.appcompat:appcompat:1.7.0'
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

Gradle 属性文件

Gradle 还包括两个属性文件，位于您的根项目目录中，您可以使用它们为 Gradle 构建工具包本身指定设置

gradle.properties
这是您可以配置项目范围的 Gradle 设置的地方，例如 Gradle 守护程序的最大堆大小。有关更多信息，请参阅构建环境。
local.properties
配置构建系统的本地环境属性，包括以下内容
  • ndk.dir - NDK 的路径。此属性已弃用。任何下载的 NDK 版本都安装在 Android SDK 目录中的 ndk 目录中。
  • sdk.dir - Android SDK 的路径。
  • cmake.dir - CMake 的路径。
  • ndk.symlinkdir - 在 Android Studio 3.5 及更高版本中，创建一个指向 NDK 的符号链接，该符号链接可能比已安装的 NDK 路径更短。

将 NDK 重新映射到更短的路径（仅限 Windows）

在 Windows 中，已安装的 NDK 文件夹中的工具（例如 ld.exe）最终会拥有很长的路径。这些工具对很长的路径支持不佳。

要创建更短的路径，请在 local.properties 中设置属性 ndk.symlinkdir 以请求 Android Gradle 插件创建指向 NDK 的符号链接。该符号链接的路径可以比现有的 NDK 文件夹更短。例如，ndk.symlinkdir = C:\ 会生成以下符号链接：C:\ndk\19.0.5232133

将项目与 Gradle 文件同步

当您对项目中的构建配置文件进行更改时，Android Studio 需要您同步项目文件，以便它可以导入您的构建配置更改并运行一些检查以确保您的配置不会创建构建错误。

要同步您的项目文件，请在您进行更改时出现的通知栏中点击**立即同步**，如图 1 所示，或从菜单栏中点击**同步项目**。如果 Android Studio 在您的配置中发现任何错误——例如，您的源代码使用仅在高于您的 compileSdkVersion 的 API 级别中才可用的 API 功能——**消息**窗口会描述该问题。

图 1. 将项目与 Android Studio 中的构建配置文 件同步。

源集

Android Studio 在逻辑上将每个模块的源代码和资源分组到源集中。当您创建一个新模块时，Android Studio 会在该模块中创建一个 main/ 源集。模块的 main/ 源集包含其所有构建变体使用的代码和资源。

其他源集目录是可选的，Android Studio 不会在您配置新的构建变体时自动为您创建它们。但是，创建类似于 main/ 的源集有助于组织 Gradle 仅在构建应用程序的某些版本时才应使用的文件和资源。

src/main/
此源集包含所有构建变体共有的代码和资源。
src/buildType/
创建此源集以包含仅针对特定构建类型使用的代码和资源。
src/productFlavor/
创建此源集以包含仅针对特定产品风味的代码和资源。

注意：如果您将构建配置为组合多个产品风味，则可以为风味维度之间每个产品的组合创建源集目录： src/productFlavor1ProductFlavor2/。

src/productFlavorBuildType/
创建此源集以包含仅针对特定构建变体使用的代码和资源。

例如，要生成应用程序的“fullDebug”版本，构建系统会合并以下源集中的代码、设置和资源。

  • src/fullDebug/（构建变体源集）
  • src/debug/（构建类型源集）
  • src/full/（产品风味源集）
  • src/main/（主源集）

注意：当您在 Android Studio 中创建新文件或目录时，请使用文件 > 新建菜单选项为特定源集创建它。您可以选择的源集基于您的构建配置，如果目录不存在，Android Studio 会自动创建必要的目录。

如果不同的源集包含同一文件的不同版本，Gradle 会使用以下优先级顺序来决定使用哪个文件。左侧的源集会覆盖右侧源集的文件和设置。

构建变体 > 构建类型 > 产品风味 > 主源集 > 库依赖项

这使 Gradle 可以使用特定于您尝试构建的构建变体的文件，同时重用对应用程序的其他版本通用的活动、应用程序逻辑和资源。

当合并多个清单时，Gradle 会使用相同的优先级顺序，以便每个构建变体可以在最终清单中定义不同的组件或权限。要详细了解如何创建自定义源集，请阅读创建源集。

版本目录

如果您的构建包含具有共同依赖项的多个模块，或者您有多个具有共同依赖项的独立项目，我们建议您使用版本目录或物料清单 (BOM) 来指定共同版本。

其他构建系统

可以使用 Bazel 构建 Android 应用，但这不受官方支持。Android Studio 不正式支持 Bazel 项目。

要更好地了解使用 Bazel 构建的当前限制，请查看已知问题。