建構設定

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 外掛程式會為您執行大部分的建構程序,但瞭解建構程序的特定切面,有助您根據需求調整建構作業。

不同專案的建構目標也會有所差異。例如,第三方程式庫的建構作業會產生 Android ARchive (AAR) 或 Java Archive (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。

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 會自動為您建立部分檔案,並根據適當預設值填入資料。專案檔案結構具有下列版面配置:

└── 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 建構設定檔是 Android 應用程式標準專案結構的一部分。因此,在開始設定建構作業之前,請務必先瞭解相關檔案的適用範圍與目的,以及其所定義的 DSL 基本元素。

Gradle 包裝函式檔案

Gradle 包裝函式 (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. 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.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.1.0" apply false
    id("com.android.library") version "8.1.0" 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.1.0' apply false
    id 'com.android.library' version '8.1.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.20' apply false
}