建構設定

Android 建構系統會編譯應用程式資源和原始碼，並封裝至 APK 或 Android App Bundle，供您測試、部署、簽署及發布。

Android Studio 會使用進階建構工具包 Gradle 自動執行及管理建構程序，可讓您靈活定義自訂建構設定。每項建構設定都能定義其專屬的程式碼和資源組合，同時也能重複使用應用程式所有版本共用的部分。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 建構系統，您無須修改應用程式的核心來源檔案，即可建立自訂建構設定。本頁內容將帶您瞭解 Android 建構系統的運作方式，以及該系統如何協助您自訂及自動執行多項建構設定。如要進一步瞭解如何部署應用程式，請參閱「建構並執行應用程式」一文。如果想立即使用 Android Studio 建立自訂建構設定，請參閱「設定建構變數」一文。

建構程序

建構程序牽涉到許多工具和程序的運作，這些工具和程序會將專案轉換為 Android 應用程式套件 (APK) 或 Android App Bundle (AAB)。

Android Gradle 外掛程式會為您執行大部分的建構程序，但瞭解建構程序的特定切面，有助您根據需求調整建構作業。

不同專案的建構目標也會有所差異。例如，第三方程式庫的建構作業會產生 AAR 或 JAR 程式庫。不過，應用程式是最常見的專案類型，應用程式專案的建構作業會產生用於偵錯或發布的應用程式 APK 或 AAB，供您部署、測試或發布給外部使用者。

儘管本頁重點在於應用程式開發，但其中許多建構步驟和概念皆常見於多數建構類型。

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。

建構設定檔

建立自訂建構設定時，您需要變更一或多個建構設定檔或 build.gradle 檔案。這些純文字檔會使用領域特定語言 (DSL) 描述建構邏輯，並利用 Groovy 或 Kotlin 指令碼加以操控。上述提及的 Groovy 是 Java 虛擬機器 (JVM) 的動態語言，而 Kotlin 指令碼則是 Kotlin 語言的變種版本。

您不需要瞭解 Groovy 或 Kotlin 指令碼即可開始設定建構作業，因為 Android Gradle 外掛程式已提供需要使用的大多數 DSL 元素。如要進一步瞭解 Android Gradle 外掛程式 DSL，請參閱 Groovy 的 DSL 參考說明文件。Kotlin 指令碼也需要使用基礎 Gradle Kotlin DSL。

啟動新專案時，Android Studio 會自動為您建立一些檔案 (如圖 1 所示)，並根據適當預設值填入資訊。

有些 Gradle 建構設定檔是 Android 應用程式標準專案結構的一部分。因此，在開始設定建構作業之前，請務必先瞭解相關檔案的適用範圍與目的，以及其所定義的 DSL 基本元素。

Gradle 設定檔

settings.gradle 檔案 (適用於 Groovy) 或 settings.gradle.kts 檔案 (適用於 Kotlin 指令碼) 位於專案根目錄中。這個設定檔可定義專案層級的存放區設定，並告知 Gradle 應在建構應用程式時納入哪些模組。多模組專案必須指定應加入至最終版本的所有模組。

在大多數專案中，預設的檔案內容如下所示：

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’

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.gradle 檔案 (適用於 Groovy) 或 build.gradle.kts 檔案 (適用於 Kotlin 指令碼) 位於專案根目錄中，可定義適用於專案中所有模組的依附元件。根據預設，頂層建構檔案會使用 plugins 區塊，定義專案中所有模組共用的 Gradle 依附元件。此外，頂層建構檔案也包含負責清除建構目錄的程式碼。

以下程式碼範例說明建立新專案後，頂層 build.gradle 檔案中的預設設定和 DSL 元素：

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 '7.4.1' apply false
    id 'com.android.library' version '7.4.1' apply false
    id 'org.jetbrains.kotlin.android' version '1.8.10' apply false
}

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 "7.4.1" apply false
    id("com.android.library") version "7.4.1" apply false
    id("org.jetbrains.kotlin.android") version "1.8.10" apply false
}

使用額外屬性設定全專案的屬性 (已淘汰)

針對包含多個模組的 Android 專案，您可以在專案層級定義特定屬性，並與所有模組共用這些屬性，這個做法可能大有用處。只要在頂層 build.gradle 檔案 (適用於 Groovy) 或 build.gradle.kts 檔案 (適用於 Kotlin 指令碼) 的 ext 區塊中加入額外屬性即可。

// This block encapsulates custom properties and makes them available to all
// modules in the project. The following are only a few examples of the types
// of properties you can define.
ext {
    sdkVersion = 33
    // You can also create properties to specify versions for dependencies.
    // Having consistent versions between modules can avoid conflicts with behavior.
    appcompatVersion = "1.6.1"
    ...
}
...

// This block encapsulates custom properties and makes them available to all
// modules in the project. The following are only a few examples of the types
// of properties you can define.
ext {
    extra["sdkVersion"] = 33
    // You can also create properties to specify versions for dependencies.
    // Having consistent versions between modules can avoid conflicts with behavior.
    extra["appcompatVersion"] = "1.6.1"
    ...
}
...

如要從相同專案中的模組存取這些屬性，請在模組的 build.gradle 檔案中使用以下語法。

android {
    // Use the following syntax to access properties you defined at the project level:
    // rootProject.ext.property_name
    compileSdk rootProject.ext.sdkVersion
    ...
}
...
dependencies {
    implementation "androidx.appcompat:appcompat:${rootProject.ext.appcompatVersion}"
    ...
}

android {
    // Use the following syntax to access properties you defined at the project level:
    // rootProject.extra["property_name"]
    compileSdk = rootProject.extra["sdkVersion"]

    // Alternatively, you can access properties using a type safe delegate:
    val sdkVersion: Int by rootProject.extra
    ...
    compileSdk = sdkVersion
}
...
dependencies {
    implementation("androidx.appcompat:appcompat:${rootProject.ext.appcompatVersion}")
    ...
}

模組層級建構檔案

模組層級 build.gradle 檔案 (適用於 Groovy) 或 build.gradle.kts (適用於 Kotlin 指令碼) 位於各個 project/module/ 目錄中，可讓您對其所在的特定模組調整建構設定。調整相關建構設定可讓您提供自訂封裝選項，例如額外的建構類型和變種版本，並可覆寫 main/ 應用程式資訊清單或頂層 build.gradle/build.gradle.kts 檔案中的相關設定。

以下的 Android 應用程式模組 build.gradle 檔案範例，概要說明部分基本的 DSL 元素和設定：

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

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

/**
 * 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.6.1'
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

/**
 * 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")
}

/**
 * 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"
        }
    }
}

/**
 * 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.6.1")
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))
}

Gradle 屬性檔案

Gradle 也包含兩個位於專案根目錄中的屬性檔案，可用來指定 Gradle 建構工具包本身的設定：

gradle.properties

您可以在這裡調整專案層級的 Gradle 設定，例如 Gradle Daemon 的堆積大小上限。詳情請參閱「建構環境」一文。

local.properties

設定建構系統的本機環境屬性，包括：

• ndk.dir - 到 NDK 的路徑。這項屬性已淘汰。任何下載的 NDK 版本都會安裝在 Android SDK 目錄的 ndk 目錄中。
• sdk.dir - 指向 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 會要求您同步處理專案檔案，以便匯入建構設定的變更內容，並執行相關檢查，確認您的設定不會發生建構錯誤。

如要同步處理專案檔案，請您進行變更後顯示的通知列中按一下「Sync Now」(如圖 2 所示)，或按一下選單列中的「Sync Project」圖示 。如果 Android Studio 發現您的設定有誤，例如原始碼使用了只會在 compileSdkVersion 以上的 API 級別中提供的 API 功能，就會透過「Messages」視窗說明問題。

來源集

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 中新建檔案或目錄時，請依序點選「File」>「New」選單選項，為特定來源集建立檔案或目錄。可供選擇的來源集取決於您的建構設定。如果所需的目錄不存在，Android Studio 就會自動建立。

如果不同來源集包含相同檔案的不同版本，Gradle 會按照下列優先順序決定要使用的檔案。左側來源集會覆寫右側來源集的檔案和設定：

建構變數 > 建構類型 > 變種版本 > 主要來源集 > 程式庫依附元件

這樣一來，Gradle 就能按照您要建立的建構變化版本選擇專用的檔案，同時重複使用其他應用程式版本常見的活動、應用程式邏輯和資源。

合併多個資訊清單時，Gradle 會使用相同的優先順序，因此每個建構變數都能在最終資訊清單中定義不同的元件或權限。如要進一步瞭解如何建立自訂來源集，請參閱「建立來源集」相關說明。

其他建構系統

您可以使用 Bazel 建構 Android 應用程式，但系統並未正式提供支援。Android Studio 並未正式支援 Bazel 專案。

如要進一步瞭解使用 Bazel 進行建構的目前限制，請參閱已知問題。