透過指令列建構應用程式

您可使用 Gradle 包裝函式指令列工具在 Android 專案中執行所有建構工作。可當做 Windows 的批次檔案 (gradlew.bat) 以及 Linux 和 Mac 的殼層指令碼 (gradlew.sh) 使用，可以從您使用 Android Studio 創建的每個專案的根目錄中存取。

如要執行包裝函式工作，請從終端機視窗使用下列其中一個指令 (在 Android Studio 中，依序選取「View」(檢視) >「Tool Windows」(工具視窗) >「Terminal」(終端機) )：

• 在 Windows 命令 Shell 中：

  gradlew task-name

• 在 Mac、Linux 或 Windows PowerShell 上：

  ./gradlew task-name

如要查看專案所有可用的建構工作清單，請執行 tasks：

gradlew tasks

本頁其餘部分將說明使用 Gradle 包裝函式建構及執行應用程式的基本概念。如要進一步瞭解如何設定 Android 版本，請參閱設定版本。

如果您偏好使用 Android Studio 工具，而非指令列工具，請參閱建構並執行應用程式。

關於版本類型

根據預設，每個 Android 應用程式都有兩種建構類型：一種是針對應用程式進行偵錯；偵錯以及向使用者發布您的應用程式發布版本。每個建構作業產生的輸出內容都必須使用憑證簽署，才能將應用程式部署至裝置。偵錯版本是使用 SDK 工具提供的偵錯金鑰自動簽署 (該程式不安全，而且無法發布至 Google Play 商店)，發布版本必須使用您的私密金鑰簽署。

如果您要建構應用程式以便發布，請務必使用適當的簽署金鑰簽署應用程式。但如果您才剛開始使用，請建立偵錯 APK，以在模擬器或已連結的裝置上快速執行應用程式。

您也可以在 build.gradle.kts 檔案中定義自訂建構類型，並透過加入 debuggable true 將其設為偵錯版本簽署。詳情請參閱「設定建構變化版本」。

建立及部署 APK

雖然建立應用程式套件是封裝應用程式並上傳至 Play 管理中心的最佳方式，但如果您要快速測試偵錯版本，則較適合建立 APK。與其他使用者共用您的應用程式做為可部署成果。

建立偵錯 APK

如要立即測試應用程式並進行偵錯，您可以建立偵錯 APK。偵錯 APK 是由 SDK 工具提供的偵錯金鑰簽署，並可透過 adb 進行偵錯。

如要建立偵錯 APK，請開啟指令列並前往專案目錄的根目錄。如要啟動偵錯版本，請叫用 assembleDebug 工作：

gradlew assembleDebug

這項操作會在 project_name/module_name/build/outputs/apk/ 中建立名為 module_name-debug.apk 的 APK。這個檔案已經使用偵錯金鑰進行簽署，且與 zipalign 對齊，因此您可以在裝置上安裝該檔案。

或者，如要建構 APK 並立即安裝在執行模擬器或已連結的裝置上，請改為叫用 installDebug：

gradlew installDebug

上述工作名稱中的「偵錯」部分只是建構變化版本名稱的大小寫版本，因此可以換成您想要組合或安裝的任何建構類型或變化版本。例如，如果您擁有「試用版」變種版本，就可以使用 assembleDemoDebug 工作建構偵錯版本。

如要查看每個變化版本的所有建構和安裝工作 (包括解除安裝工作)，請執行 tasks 工作。

另請參閱在模擬器上執行應用程式和在裝置上執行應用程式一節。

建立版本組合或 APK

當您準備發布及發行應用程式時，您必須建立使用私密金鑰簽署的發布套件或 APK。詳情請參閱「透過指令列簽署應用程式」一節。

將應用程式部署至模擬器

如要使用 Android Emulator，您必須使用 Android Studio 建立 Android 虛擬裝置 (AVD)。

取得 AVD 後，請按照下列步驟啟動 Android Emulator 並安裝應用程式：

1. 在指令列中，前往 android_sdk/tools/ 並指定您的 AVD 啟動模擬器：

   emulator -avd avd_name

   如果不確定 AVD 名稱，請執行 emulator -list-avds。

2. 現在，您可以參閱構建偵錯 APK 或 adb 工具一節提及的 Gradle 安裝工作，選取一種方式安裝您的應用程式。

   如果是透過開發人員預覽 SDK (若 targetSdkVersion 為字母而非數字)，請務必加上 -t 選項 install 指令安裝測試 APK。

   adb install path/to/your_app.apk
   

   您建構的所有 APK 都會儲存在 project_name/module_name/build/outputs/apk/ 中。

詳情請參閱在 Android Emulator 上執行應用程式。

將應用程式部署至實體裝置

您必須先在裝置上啟用「USB debugging」(USB 偵錯)」，才能在裝置上執行應用程式。您可以在「Settings」(設定) >「Developer options」(開發人員選項) 找到這個選項。

注意：在 Android 4.2 及以上版本中，「Developer options」(開發人員選項) 預設為隱藏。如要啟用這項功能，請依序前往「Settings」(設定) >「About phone」(關於手機)，然後輕觸七次「Build number」(版本號碼)。返回上一個畫面並找到「Developer options」(開發人員選項)。

在 USB 上設定裝置並建立連線後，您可以參閱構建偵錯 APK 或 adb 工具一節提及的 Gradle 安裝工作，選取一種方式安裝您的應用程式。

adb -d install path/to/your_app.apk

您建構的所有 APK 都會儲存在 project_name/module_name/build/outputs/apk/ 中。

詳情請參閱「在硬體裝置上執行應用程式」。

建立應用程式套件

Android App Bundle 內含您應用程式所有已編譯的程式碼和資源，但可延後產生 APK 並簽署 Google Play。與 APK 不同，您無法直接將應用程式套件部署至裝置。因此，如要快速測試或與他人共用 APK，請改為建構 APK。

如要建立應用程式套件，最簡單的方法是使用 Android Studio。但是，如果您需要透過指令列建立應用程式套件，則可使用 Gradle 或 bundletool 來進行，如以下各節所述。

使用 Gradle 建構應用程式套件

如果您希望透過指令列產生應用程式套件，請在應用程式的基本模組中執行 bundleVariant Gradle 工作。例如，下列指令會針對基本模組的偵錯版本建構應用程式套件：

./gradlew :base:bundleDebug

如要建構上傳至 Play 管理中心的已簽署套件，您必須先使用應用程式簽署資訊設定基本模組的 build.gradle.kts 檔案。詳情請參閱設定 Gradle 以簽署應用程式，接著，您可以建立應用程式發布版本，Gradle 會自動產生應用程式套件，並使用您在 build.gradle.kts 檔案中提供的簽署資訊對其進行簽署。

如果您想將應用程式套件改成獨立步驟，可以使用 jarsigner 透過指令列簽署應用程式套件。建構應用程式套件的指令如下：

jarsigner -keystore pathToKeystore app-release.aab keyAlias

注意： 您無法使用 apksigner 簽署應用程式套件。

使用 bundletool 建構應用程式套件

bundletool 是 Android Studio、Android Gradle 外掛程式和 Google Play 的指令列工具，可將應用程式的編譯程式碼和資源轉換成應用程式套件，並產生這些套件的可部署 APK。

因此，雖然使用 bundletool 測試應用程式套件並在本機重新創建 Google Play 生成 APK 的方式很有用，但您通常不需要叫用 bundletool 來構建應用程式套件本身，請改用 Android Studio 或 Gradle 工作 (如上一節所述)。

如果不想使用 Android Studio 或 Gradle 工作來建構套件 (例如使用自訂建構工具鏈)，可以在指令列使用 bundletool 建構預先編譯的程式碼和資源。如果您尚未從 GitHub 存放區下載 bundletool，請先完成這項操作。

本部分說明如何封裝應用程式的編譯程式碼和資源，以及如何透過指令列使用 bundletool，將這些項目轉換為 Android App Bundle。

以 proto 格式產生資訊清單和資源

bundletool 需要應用程式專案的某些資訊，例如應用程式資訊清單和資源，以 Google 的通訊協定緩衝區格式 (又稱為「protobuf」)，並使用 *.pb 副檔名。Protobufs 為序列化結構化資料提供一種語言中立、平台中立和可擴充的機制，雖然與 XML 類似，但較小、快速、簡單。

下載 AAPT2

您可以從 Google Maven 存放區中的最新版 AAPT2 產生應用程式資訊清單檔案和資源資料表。

注意： 請勿使用 Android 建構工具套件中包含的 AAPT2 版本，因為此 AAPT2 版本不支援 bundletool。

如要從 Google 的 Maven 存放區下載 AAPT2，請按照下列步驟操作：

1. 前往存放區索引中的「com.android.tools.build」 >「aapt2」。
2. 複製最新版 AAPT2 的名稱。

3. 請將您複製的版本名稱貼到以下網址中，並指定目標作業系統：https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/aapt2-version/aapt2-aapt2-version-[windows | linux | osx].jar

   例如，如要下載 Windows 3.2.0-alpha18-4804415 版本，請使用以下這個檔案：https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar

4. 使用瀏覽器前往網址 (AAPT2) 很快就會開始下載。

5. 解壓您剛下載的 JAR 檔案。

編譯並連結應用程式的資源

使用 AAPT2 透過下列指令編譯應用程式資源：

aapt2 compile \
project_root/module_root/src/main/res/drawable/Image1.png \
project_root/module_root/src/main/res/drawable/Image2.png \
-o compiled_resources/

注意： 雖然您可以使用 --dir 旗標將資源目錄傳遞至 AAPT2，但無論實際更改了多少檔案，系統都會重新編譯目錄中的所有檔案。

在連結階段 (AAPT2 會將各種已編譯的資源連結至單一 APK)，透過加入 --proto-format 旗標，指示 AAPT2 將應用程式的資訊清單和編譯後的資源轉換為 protobuf 格式，如下所示：

aapt2 link --proto-format -o output.apk \
-I android_sdk/platforms/android_version/android.jar \
--manifest project_root/module_root/src/main/AndroidManifest.xml \
-R compiled_resources/*.flat \
--auto-add-overlay

注意： 或者，使用 -R 旗標指定已編譯的資源時，您可以指定一個文字檔案，其中包含各個已編譯的資源，每個路徑以一個空格分隔。接著，您可以按照下列方式將文字檔傳送至 AAPT2：aapt2 link ... -R @compiled_resources.txt。

接著，您就能從輸出 APK 中擷取內容，例如應用程式的 AndroidManifest.xml、resources.pb 和其他是 protobuf 格式的資源檔案。準備輸入 bundletool 時，您需要這些檔案建構應用程式套件，如下一節所述。

封裝預先編譯的程式碼和資源

使用 bundletool 為應用程式產生應用程式套件之前，您必須先提供 ZIP 檔案，每個檔案都包含特定應用程式模組的編譯程式碼和資源。各個模組 ZIP 檔案的內容和組織與 Android App Bundle 格式非常類似。例如，您應該為應用程式的基本模組建立 base.zip 檔案，並為其編排內容，如下所示：

檔案或目錄	說明
manifest/AndroidManifest.xml	採用 protobuf 格式的模組資訊清單。
dex/...	包含一或多個應用程式編譯 DEX 檔案的目錄。檔案名稱應如下所示：classes.dex、classes2.dex、classes3.dex 等。
res/...	包含所有裝置配置的 Protobuf 格式的模組資源。子目錄和檔案應與一般 APK 類似。
root/...、assets/... 和 lib/...	這些目錄與 Android App Bundle 格式部分所述的目錄相同。
resources.pb	採用 protobuf 格式的應用程式資源資料表。

為每個應用程式模組備妥 ZIP 檔案後，您可以將檔案傳送至 bundletool 來建立應用程式套件，如下一節所述。

使用 bundletool 建立應用程式套件

如要建構應用程式套件，請使用 bundletool build-bundle 指令，如下所示：

bundletool build-bundle --modules=base.zip --output=mybundle.aab

注意： 如果您打算發布應用程式套件，就必須使用 jarsigner 簽署。您無法使用 apksigner 簽署應用程式套件。

下表詳細說明 build-bundle 指令的旗標：

標記	說明
--modules=path-to-base.zip, path-to-module2.zip,path-to-module3.zip	指定 bundletool 用來建立應用程式套件的模組 ZIP 檔案清單。
--output=path-to-output.aab	指定輸出 *.aab 檔案的路徑和檔案名稱。
--config=path-to-BundleConfig.json	指定選用設定檔的路徑，您可以使用該設定檔自訂建構程序。詳情請參閱「自訂下游 APK 產生作業」一節。
--metadata-file=target-bundle-path:local-file-path	指示 bundletool 將選用的中繼資料檔案封裝在您的應用程式套件中。您可以使用這個檔案加入資料，例如 ProGuard 對應關係或應用程式 DEX 檔案的完整清單，這項資訊對於工具鍊或應用程式商店的其他步驟可能有所幫助。 target-bundle-path 可指定應用程式套件的根路徑 (您希望將中繼資料檔案封裝的位置)，local-file-path 則會指定本機中繼資料檔案本身的路徑。

自訂下游 APK 產生

應用程式套件內含 BundleConfig.pb 檔案，該檔案提供應用商店 (例如 Google Play) 從軟體包生成 APK 時所需的中繼資料。雖然 bundletool 可以為您建立這個檔案，但是您可以在 BundleConfig.json 檔案中設定中繼資料的某些部分，並將其傳送至 bundletool build-bundle 指令：bundletool 之後會轉換並將這個檔案與每個應用程式套件中的 protobuf 版本合併。

注意： 如要進一步瞭解 JSON 是如何對應至 protobuf 格式，請參閱 JSON 對應。然而，這個資訊比這個頁面所需的資訊更進階。

例如，您可以控管要啟用或停用的設定 APK 類別。以下 BundleConfig.json 檔案範例會停用設定 APK，每個 APK 都針對不同的語言 (也就是所有語言的資源都會包含在各自的基礎 APK 或功能 APK 中)：

{
  "optimizations": {
    "splitsConfig": {
      "splitDimension": [{
        "value": "LANGUAGE",
        "negate": true
      }]
    }
  }
}

在 BundleConfig.json 檔案中，您還可以使用 glob 模式指定 APK 封裝時，要維持未壓縮的檔案類型，如下所示：

{
  "compression": {
    "uncompressedGlob": ["res/raw/**", "assets/**.uncompressed"]
  }
}

請注意，根據預設 bundletool 不會壓縮應用程式的原生程式庫 (Android 6.0 或以上版本) 和資源表格 (resources.arsc)。有關可以在 BundleConfig.json 中設定的所有內容，請參閱 bundletool config.proto 檔案，其使用 Proto3 語法寫成。

透過應用程式套件部署應用程式

如果您建構並簽署了應用程式套件，請使用 bundletool 產生 APK 並部署到裝置上。

透過指令列簽署應用程式

您無須使用 Android Studio 簽署應用程式，您可以透過指令列簽署應用程式，並使用 apksigner (適用於 APK) 或 jarsigner (應用程式套件)，或在建構期間設定 Gradle 為您簽署。無論哪種方式，您都必須先使用 keytool 產生私密金鑰，如下所示：

keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias

上方範例會提示您輸入 KeyStore 和金鑰的密碼，以及金鑰的「辨別名稱」欄位。然後將 KeyStore 儲存為 my-release-key.jks 的檔案，並儲存在目前的目錄中 (您可以將檔案移至任何所需位置)。KeyStore 包含一個 10,000 天有效的金鑰。

現在，您可以手動簽署 APK 或應用程式套件，也可以在建構程序中設定 Gradle 簽署應用程式，如以下各節所述。

透過指令列手動簽署應用程式

如要透過指令列簽署應用程式套件，可以使用 jarsigner。如果您想簽署 APK，則必須按照下列說明使用 zipalign 和 apksigner。

1. 開啟 Android Studio 中的指令列，然後依序選取「View」(檢視) >「Tool Windows」(工具視窗) >「Terminal」(終端機)，然後前往未簽署 APK 所在的目錄。

2. 使用 zipalign 對齊未簽署的 APK：

   zipalign -v -p 4 my-app-unsigned.apk my-app-unsigned-aligned.apk
   

   zipalign 可確保所有未壓縮的資料開始根據檔案開頭的特定位元組對齊，這可能會減少應用程式使用的 RAM 量。

3. 運用 apksigner 使用私密金鑰簽署 APK：

   apksigner sign --ks my-release-key.jks --out my-app-release.apk my-app-unsigned-aligned.apk
   

   以下範例使用儲存於單一 KeyStore 檔案中的私密金鑰和憑證，在 my-app-release.apk 輸出已簽署的 APK：my-release-key.jks。

   apksigner 工具支援其他簽署選項，包括使用不同的私密金鑰和憑證檔案簽署 APK 檔案，以及使用多個簽署者簽署 APK。詳情請參閱 apksigner 參考資源。

   注意事項：如要使用 apksigner 工具，您必須安裝 24.0.3 或以上版本的 Android SDK 建構工具。您可以使用 SDK Manager 更新這個套件。

4. 確認您的 APK 已簽署：

   apksigner verify my-app-release.apk
   

設定 Gradle 以簽署應用程式

開啟模組層級 build.gradle.kts 檔案，然後新增 storeFile、storePassword、keyAlias 和 keyPassword 項目的 signingConfigs {} 區塊，將該物件傳送到建構類型的 signingConfig 屬性。例如：

Kotlin

android {
    ...
    defaultConfig { ... }
    signingConfigs {
        create("release") {
            // You need to specify either an absolute path or include the
            // keystore file in the same directory as the build.gradle file.
            storeFile = file("my-release-key.jks")
            storePassword = "password"
            keyAlias = "my-alias"
            keyPassword = "password"
        }
    }
    buildTypes {
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
            ...
        }
    }
}

Groovy

android {
    ...
    defaultConfig { ... }
    signingConfigs {
        release {
            // You need to specify either an absolute path or include the
            // keystore file in the same directory as the build.gradle file.
            storeFile file("my-release-key.jks")
            storePassword "password"
            keyAlias "my-alias"
            keyPassword "password"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            ...
        }
    }
}

注意： 在這種情況下，KeyStore 和金鑰密碼會直接顯示在 build.gradle 檔案中。為提高安全性，您應從建構檔案中移除簽署資訊。

現在，當您叫用 Gradle 工作來建構應用程式時，Gradle 會為您簽署應用程式 (並執行 zipalign)。

此外，您已使用簽署金鑰設定了發布版本，因此該建構類型可以執行「安裝」工作。因此，您可以使用 installRelease 工作，在模擬器或裝置中建構、對齊、簽署及安裝版本 APK。

使用私密金鑰簽署的應用程式已準備好發布，但建議您先進一步瞭解如何發布應用程式及詳閱 Google Play 發布檢查清單。