建構設定

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 設定建構版本,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.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
}