配置您的构建

Android 构建系统会编译应用资源和源代码,并将它们打包到 APK 或 Android 应用包中,您可以对其进行测试、部署、签名和分发。

Gradle 构建概述Android 构建结构 中,我们讨论了构建概念和 Android 应用的结构。现在是时候配置构建了。

Android 构建术语表

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

构建类型

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

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

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

产品风格
产品风格代表您可以发布给用户的应用的不同版本,例如免费版和付费版。您可以自定义产品风格以使用不同的代码和资源,同时共享和重用所有应用版本通用的部分。产品风格是可选的,您必须手动创建它们。要开始创建应用的不同版本,请了解如何 配置产品风格
构建变体
构建变体是构建类型和产品风格的组合,是 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 语言的一种变体)。您也可以使用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.7.0" apply false
    id("com.android.library") version "8.7.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.7.0' apply false
    id 'com.android.library' version '8.7.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
图 1. 构建中的 Android SDK
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的值。

注意:compileSdktargetSdk的值不必相同。请记住以下基本原则

  • 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 需要您同步项目文件,以便它可以导入您的构建配置更改并运行一些检查以确保您的配置不会创建构建错误。

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

图 2. 在 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 构建的当前限制,请参阅已知问题