bundletool

bundletool 是 Android Gradle 外掛程式 Android Studio 及 Google Play 用於建構 Android App Bundle 的基礎工具,會將應用程式套件轉換為部署至裝置的各種 APK。您也可以使用 bundletool 為指令列工具,以便自行建構應用程式套件,並重新建立 Google Play 的伺服器端 APK 應用程式版本。

下載 bundletool

如果您尚未下載 bundletool 檔案,請前往 GitHub 存放區

建構應用程式套件

您應使用 Android Studio 和 Gradle 的 Android 外掛程式建構並簽名 Android App Bundle。然而,如果無法使用 IDE,例如您使用的是持續建構伺服器,那麼您也可以透過指令列建構應用程式套件然後使用 jarsigner 申請驗證。

如要進一步瞭解如何使用 bundletool 建構應用程式套件,請參閱使用 bundletool 建構應用程式套件

透過應用程式套件產生一組 APK

建構 Android App Bundle 後,您必須測試 Google Play 使用 Android App Bundle 產生 APK 的情形,以及這些 APK 部署到裝置上之後的行為。建議您考慮透過 bundletool 指令列工具在本機端測試應用程式套件,以及透過 Google Play 將套裝組合上傳至 Play 管理中心,並使用測試群組。本節說明如何使用 bundletool 在本機測試您的應用程式套件。

bundletool 從您的應用程式套件產生 APK 時,系統會將 APK 包含在名為「APK 集的封存檔案」的容器中,而容器會使用 .apks 副檔名。如要為應用程式從應用程式套件支援的所有裝置設定產生 APK 設定,請使用 bundletool build-apks 指令,如下所示。

bundletool build-apks --bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks

如要將 APK 部署到裝置,您必須一併加入應用程式的簽名資訊,如下方指令所示。如未指定簽名資訊,bundletool 會嘗試使用偵錯金鑰簽名您的 APK。

bundletool build-apks --bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks
--ks=/MyApp/keystore.jks
--ks-pass=file:/MyApp/keystore.pwd
--ks-key-alias=MyKeyAlias
--key-pass=file:/MyApp/key.pwd

下表詳細說明了在使用 bundletool build-apks 指令時,您可以設定的各種標記和選項。只有 --bundle--output 皆為選用,所有其他標記則為選用項目。

檢舉 說明
--bundle=path (必要) 指定您透過 Android Studio 建構的應用程式套件路徑。詳情請參閱「建構專案」
--output=path (必要) 指定輸出「.apks」檔案的名稱,其中包含應用程式的所有 APK 構件。如要在裝置上測試這個檔案中的成果,請前往一節,瞭解如何將 APK 部署至已連結的裝置
--overwrite 如要覆寫使用 --output 選項指定的相同路徑的任何現有輸出檔案,請加入此標記。如果您未提供這個標記,且輸出檔案已存在,您會收到建構錯誤。
--aapt2=path 指定 AAPT2 的自訂路徑。 根據預設,bundletool 包含自己的 AAPT2 版本。
--ks=path 指定用來簽名 APK 的部署 KeyStore 路徑。這個標記是選用的。如未提供,bundletool 會使用偵錯簽名金鑰簽您的 APK。
--ks-pass=pass:password

--ks-pass=file:/path/to/file
指定 KeyStore 密碼。如果您要以純文字指定密碼,請使用 pass: 進行認證。 如要將路徑傳送至含有密碼的檔案,請使用 file: 進行認證。如果您使用 --ks 標記指定 KeyStore,但沒有指定 --ks-passbundletool 會提示您透過指令列輸入密碼。
--ks-key-alias=alias 指定要使用的簽名金鑰別名。
--key-pass=pass:password

--key-pass=file:/path/to/file
指定簽名金鑰的密碼。如果您要以純文字指定密碼,請使用 pass: 進行認證。 如要將路徑傳送至含有密碼的檔案,請使用 file: 進行認證。

如果這組密碼與 KeyStore 本身的密碼相同,請略過這個標記。

--connected-device 指示 bundletool 建構以已連結裝置設定為目標的 APK。如果您未提供這個標記,bundletool 會針對應用程式支援的所有裝置設定產生 APK。
--device-id=serial-number 如果您有多部已連結的裝置,請使用此標記來指定您要部署應用程式的裝置序號。
--device-spec=spec_json 使用標記提供 .json 檔案的路徑,以指定您要指定的裝置設定。詳情請參閱建構及使用裝置規格 JSON 檔案一節。
--mode=universal 如果希望 bundletool 僅建構包含您應用程式所有程式碼及資源的單一 APK,以便該 APK 與您在應用程式支援的所有裝置相容,請將模式設為 universal

附註: bundletool 只有功能模組在通用 APK 的資訊清單中指定 <dist:fusing dist:include="true"/>。詳情請參閱功能模組資訊清單

請注意,這些 APK 比針對特定裝置設定最佳化的 APK 還要大。然而,您可以輕鬆與內部測試人員分享資訊,例如,他們可以利用多種裝置設定來測試應用程式。

--local-testing 使用這項標記來啟用應用程式套件,進行本機測試。 本機測試可讓您快速上傳至 Google Play 伺服器,以反覆進行測試。

如需如何使用 --local-testing 標記測試模組安裝的範例,請參閱本機測試模組安裝

將 APK 部署到已連結的裝置

產生一組 APK 後,bundletool 即可從該集合部署正確的 APK 組合到已連結的裝置。

舉例來說,如果您的已連結的裝置搭載 Android 5.0 (API 級別 21) 或以上版本,bundletool 會推送基礎 APK、功能模組 APK 和設定 APK,以便在裝置上執行應用程式。或者,如果您的已連結的裝置搭載的是 Android 4.4 (API 級別 20) 或以下版本,則 bundletool 會尋找相容的多個 APK,並將其部署至您的裝置。

如要從 APK 集部署應用程式,請使用 install-apks 指令並使用 --apks=/path/to/apks 標記指定 APK 設定的路徑,如下所示。(如果您連接多部裝置,請加入 --device-id=serial-id 標記來指定目標裝置)。

bundletool install-apks --apks=/MyApp/my_app.apks

產生裝置專用的一組 APK

如果您不想為應用程式支援的所有裝置設定建構一組 APK,可以使用 --connected-device 選項建構僅指定已連結的裝置設定 APK,如下所示。(如果您連接多部裝置,請加入 --device-id=serial-id 標記來指定目標裝置)。

bundletool build-apks --connected-device
--bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks

產生並使用裝置規格 JSON 檔案

bundletool 可以產生指定 JSON 檔案所指定的裝置設定的 APK 組合。如要先為已連結的裝置產生 JSON 檔案,請執行下列指令:

bundletool get-device-spec --output=/tmp/device-spec.json

bundletool 會在工具所在的目錄中建立裝置的 JSON 檔案。您可以將此檔案傳送至 bundletool 以產生一組指定該 JSON 檔案所描述設定的 APK,如下所示:

bundletool build-apks --device-spec=/MyApp/pixel2.json
--bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks

手動建立裝置規格 JSON

如果您無法存取要建構指定 APK 的裝置 (例如好友想要試用您未安裝的裝置),您可以按照下列格式手動建立 JSON 檔案:

{
  "supportedAbis": ["arm64-v8a", "armeabi-v7a"],
  "supportedLocales": ["en", "fr"],
  "screenDensity": 640,
  "sdkVersion": 27
}

接著,請按照上一節的說明,將這個 JSON 傳送至 bundle extract-apks 指令。

從現有的 APK 組合中擷取裝置專用的 APK

如果您已設定現有 APK,且想要從指定特定裝置設定的 APK 子集擷取,您可以使用 extract-apks 指令並指定裝置規格 JSON,如下所示:

bundletool extract-apks
--apks=/MyApp/my_existing_APK_set.apks
--output-dir=/MyApp/my_pixel2_APK_set.apks
--device-spec=/MyApp/bundletool/pixel2.json

評估 APK 組合中的 APK 下載大小

如要測量 APK 組合中透過 Wi-Fi 無線提供的預估 APK 下載大小,請使用 get-size total 指令:

bundletool get-size total --apks=/MyApp/my_app.apks

您可以使用下列標記修改 get-size total 指令的行為:

檢舉 說明
--apks=path (必要) 指定現有 APK 組合檔案的下載路徑大小。
--device-spec=path 指定裝置規格檔案的路徑 (來自 get-device-spec 或手動建構),以供比對。 您可以指定部分路徑來評估一組設定。
--dimensions=dimensions 指定在計算大小預估值時所採用的維度。可接受以逗號分隔的清單,包含 SDKABISCREEN_DENSITYLANGUAGE。如要測量所有維度,請指定 ALL
--instant 測量免安裝即用 APK 的下載大小,而非安裝專用的 APK。根據預設,bundletool 會測量可安裝的 APK 下載大小。
--modules=modules 指定在 APK 中設定要納入考量的模組清單,並以半形逗號分隔。bundletool 指令會自動包含指定組合的任何相依模組。根據預設,指令會計算在首次下載期間安裝的所有模組的下載大小。

其他資源

如要進一步瞭解如何使用 bundletool,請嘗試下列資源。

程式碼研究室

  • 第一個 Android App Bundle:這個程式碼研究室可探索 Android App Bundle 的基本原則,並說明如何透過 Android Studio 快速開始建構應用程式。這個程式碼研究室也會探索如何使用 bundletool 測試應用程式套件。