The Android Developer Challenge is back! Submit your idea before December 2.

bundletool

创建 Android App Bundle 后,您必须测试 Google Play 使用该 Android App Bundle 生成 APK 的情形,以及这些 APK 部署到设备上之后的表现。您应该考虑通过以下两种方式来测试 app bundle:在本地使用 bundletool 命令行工具进行测试,以及通过 Google Play 将您的 app bundle 上传到 Play 管理中心并使用测试轨道进行测试。本页介绍了如何使用 bundletool 在本地测试您的 app bundle。

bundletool 是一种底层工具,可供 Gradle、Android Studio 和 Google Play 用于编译 Android App Bundle 或将 app bundle 转换为部署到设备的各种 APK。您也可以将 bundletool 作为一种命令行工具,用于重新创建、检查和验证应用 APK 的 Google Play 服务器端版本。

您应该使用 Android Studio 和 Android Plugin for Gradle 编译 Android App Bundle 并为其签名。但是,如果无法使用 IDE(例如,因为您使用的是连续编译服务器),您也可以从命令行编译 app bundle 并使用 jarsigner 为其签名。

默认情况下,IDE 不会使用 app bundle 将您的应用部署到本地设备进行测试。但是,您可以修改运行/调试配置,并选择从 app bundle 部署 APK 的选项,以查看该选项对应用执行的影响。

下载 bundletool

如果您还没有下载 bundletool,请从 GitHub 代码库下载 bundletool

从 app bundle 生成一组 APK

bundletool 从您的 app bundle 生成 APK 时,它会将这些 APK 包含在一个名为“APK set archive”的容器中,该容器以 .apks 作为文件扩展名。要从 app bundle 为应用支持的所有设备配置生成一组 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 编译的 app bundle 的路径。要了解详情,请参阅编译您的项目
--output=path (必需)指定“.apks”输出文件的名称,其中包含了应用的所有 APK 工件。要了解如何在设备上测试此文件中的工件,请转至介绍如何将 APK 部署到已连接设备的部分。
--overwrite 如果您要覆盖您使用 --output 选项指定的路径上的现有输出文件,请添加此标记。如果已存在输出文件,而您又未添加此标记,则会发生编译错误。
--aapt2=path 指定 AAPT2 的自定义路径。默认情况下,bundletool 包含自己的 AAPT2 版本。
--ks=path 指定用于为 APK 签名的部署密钥库的路径。此标记是可选的。如果您不添加此标记,bundletool 会尝试使用调试签名密钥为您的 APK 签名。
--ks-pass=pass:password

--ks-pass=file:/path/to/file
指定密钥库的密码。如果您指定纯文本格式的密码,请使用 pass: 限定该密码。如果您要传递包含该密码的文件的路径,请使用 file: 限定该路径。如果您使用 --ks 标记指定密钥库,而未指定 --ks-pass,则 bundletool 会提示您从命令行输入密码。
--ks-key-alias=alias 指定要使用的签名密钥的别名。
--key-pass=pass:password

--key-pass=file:/path/to/file
指定签名密钥的密码。如果您指定纯文本格式的密码,请使用 pass: 限定该密码。如果您要传递包含该密码的文件的路径,请使用 file: 限定该路径。

如果此密码与密钥库的密码相同,则可以省略此标记。

--connected-device 指示 bundletool 针对已连接的设备的配置生成 APK。如果您不添加此标记,bundletool 会为您的应用支持的所有设备配置生成 APK。
--device-id=serial-number 如果您有多个已连接的设备,请使用此标记指定要部署应用的设备的序列号。
--device-spec=spec_json 使用此标记提供 .json 文件的路径,该文件指定了您要针对其生成 APK 的目标设备配置。要了解详情,请转至介绍如何创建和使用设备规范 JSON 文件的部分。
--mode=universal 如果您希望 bundletool 只生成一个包含应用的所有代码和资源的 APK,以使该 APK 与应用支持的所有设备配置兼容,请将模式设置为 universal

注意bundletool 仅包含动态功能模块,这些模块在通用 APK 中的对应清单中指定 <dist:fusing dist:include="true"/>。要了解详情,请参阅动态功能模块清单

请注意,这些 APK 要比针对特定设备配置优化过的 APK 更大。但是,这些 APK 更便于与内部测试人员共享,例如想在多种设备配置上测试您的应用的测试人员。

将 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 集中的 APK 将在压缩后通过网络提供。要估算这些 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,请使用以下资源。

Codelab

  • 您的首个 Android App Bundle:一个探索 Android App Bundle 基本原理的 codelab,向您展示了如何使用 Android Studio 快速开始构建您自己的 App Bundle。此 codelab 还探索了如何使用 bundletool 测试 app bundle。