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。