从命令行构建您的应用

您可以使用 Gradle 封装器 命令行工具执行 Android 项目中所有可用的构建任务。它在 Windows 上是一个批处理文件（gradlew.bat），在 Linux 和 Mac 上是一个 shell 脚本（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 应用都有两种可用的构建类型：一种用于调试应用（即 debug 构建），另一种用于向用户发布应用（即 release 构建）。每种构建的输出都必须使用证书签名，然后才能将应用部署到设备上。debug 构建会自动使用 SDK 工具提供的 debug 密钥签名（不安全，不能用于发布到 Google Play 商店），而 release 构建必须使用您自己的私钥签名。

如果您想构建用于发布的应用，则务必使用相应的签名密钥签署您的应用。但是，如果您刚开始，可以通过构建 debug APK 快速在模拟器或连接的设备上运行您的应用。

您还可以在您的 build.gradle.kts 文件中定义自定义构建类型，并通过包含 debuggable true 将其配置为 debug 构建。如需了解详情，请参阅配置构建变体。

构建并部署 APK

虽然构建应用包是打包您的应用并将其上传到 Play 管理中心​​的最佳方式，但当您想快速测试 debug 构建或与他人共享可部署工件形式的应用时，构建 APK 更为合适。

构建 debug APK

对于即时应用测试和调试，您可以构建 debug APK。debug APK 使用 SDK 工具提供的 debug 密钥签名，并允许通过 adb 进行调试。

要构建 debug APK，请打开命令行并导航到项目目录的根目录。要启动 debug 构建，请调用 assembleDebug 任务

gradlew assembleDebug

这会在 project_name/module_name/build/outputs/apk/ 中创建一个名为 module_name-debug.apk 的 APK。该文件已使用 debug 密钥签名并与 zipalign 对齐，因此您可以立即将其安装到设备上。

或者，要构建 APK 并立即将其安装在正在运行的模拟器或已连接的设备上，请改为调用 installDebug

gradlew installDebug

上述任务名称中的“Debug”部分只是构建变体名称的驼峰式大小写版本，因此可以用您想要组装或安装的任何构建类型或变体替换。例如，如果您有“demo”产品变种，则可以使用 assembleDemoDebug 任务构建 debug 版本。

要查看每个变体（包括卸载任务）可用的所有构建和安装任务，请运行 tasks 任务。

另请参阅关于如何在模拟器上运行您的应用以及如何在设备上运行您的应用的部分。

构建发布包或 APK

当您准备好发布和分发您的应用时，您必须构建一个使用您的私钥签名的发布包或 APK。如需了解详情，请转到关于如何从命令行签署您的应用的部分。

将应用部署到模拟器

要使用 Android 模拟器，您必须使用 Android Studio 创建一个 Android 虚拟设备 (AVD)。

拥有 AVD 后，请按以下步骤启动 Android 模拟器并安装您的应用

  1. 在命令行中，导航到 android_sdk/tools/ 并通过指定您的 AVD 启动模拟器

    emulator -avd avd_name

    如果您不确定 AVD 名称，请执行 emulator -list-avds。

  2. 现在，您可以使用关于如何构建 debug APK 的部分中提到的 Gradle 安装任务之一，或者使用 adb 工具安装您的应用。

    如果 APK 是使用开发者预览版 SDK 构建的（如果 targetSdkVersion 是字母而不是数字），您必须在 install 命令中包含 -t 选项才能安装测试 APK。

    adb install path/to/your_app.apk

    您构建的所有 APK 都保存在 project_name/module_name/build/outputs/apk/ 中。

如需了解详情，请参阅在 Android 模拟器上运行应用。

将应用部署到物理设备

在设备上运行应用之前，您必须在设备上启用 USB 调试。您可以在 Settings > Developer options 下找到该选项。

注意：在 Android 4.2 及更高版本中，Developer options 默认是隐藏的。要使其可用，请转到 Settings > About phone 并连续点按 Build number 七次。返回上一屏幕即可找到 Developer options。

设备设置完毕并通过 USB 连接后，您可以使用关于如何构建 debug APK 的部分中提到的 Gradle 安装任务之一，或者使用 adb 工具安装您的应用

adb -d install path/to/your_app.apk

您构建的所有 APK 都保存在 project_name/module_name/build/outputs/apk/ 中。

如需了解详情，请参阅在硬件设备上运行应用。

构建应用包

Android 应用包包含应用的所有已编译代码和资源，但会将 APK 生成和签名推迟到 Google Play。与 APK 不同，您不能将应用包直接部署到设备上。因此，如果您想快速测试或与他人共享 APK，则应改为构建 APK。

构建应用包最简单的方法是使用 Android Studio。但是，如果您需要从命令行构建应用包，可以使用 Gradle 或 bundletool，如下面几节所述。

使用 Gradle 构建应用包

如果您想从命令行生成应用包，请在应用的基本模块上运行 bundleVariant Gradle 任务。例如，以下命令会为基本模块的 debug 版本构建应用包

./gradlew :base:bundleDebug

如果您想构建一个用于上传到 Play 管理中心的签名包，您需要首先使用应用的签名信息配置基本模块的 build.gradle.kts 文件。如需了解详情，请转到关于如何配置 Gradle 以签署您的应用的部分。然后，您可以例如构建应用的 release 版本，Gradle 会自动生成应用包并使用您在 build.gradle.kts 文件中提供的签名信息对其进行签名。

如果您想将应用包作为单独的步骤进行签名，您可以使用 jarsigner 从命令行签署您的应用包。构建应用包的命令是

jarsigner -keystore pathToKeystore app-release.aab keyAlias

使用 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 应用包。

以 proto 格式生成清单和资源

bundletool 要求您应用项目中的某些信息（例如应用清单和资源）采用Google 的 Protocol Buffer 格式——该格式也称为“protobuf”，并使用 *.pb 文件扩展名。Protobuf 提供了一种语言中立、平台中立且可扩展的结构化数据序列化机制——它类似于 XML，但更小、更快、更简单。

下载 AAPT2

您可以使用Google Maven 仓库中的最新版 AAPT2 以 protobuf 格式生成应用的清单文件和资源表。

要从 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/

在链接阶段，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

然后，您可以从输出 APK 中提取内容，例如应用的 AndroidManifest.xml、resources.pb 和其他资源文件——现在采用 protobuf 格式。在准备 bundletool 构建应用包所需的输入时，您需要这些文件，如下一节所述。

打包预编译代码和资源

在使用 bundletool 为您的应用生成应用包之前，您必须首先提供 ZIP 文件，每个文件都包含给定应用模块的已编译代码和资源。每个模块的 ZIP 文件的内容和组织方式与Android 应用包格式非常相似。例如，您应该为应用的基本模块创建一个 base.zip 文件，并按以下方式组织其内容

文件或目录 说明
manifest/AndroidManifest.xml 采用 protobuf 格式的模块清单。
dex/... 包含应用的一个或多个已编译 DEX 文件的目录。这些文件应按以下方式命名： classes.dex、classes2.dex、classes3.dex 等。
res/... 包含适用于所有设备配置的 protobuf 格式的模块资源。子目录和文件应与典型的 APK 组织方式类似。
root/...、assets/... 和 lib/... 这些目录与关于Android 应用包格式的部分中描述的目录相同。
resources.pb 采用 protobuf 格式的应用资源表。

为应用的每个模块准备好 ZIP 文件后，您可以将它们传递给 bundletool 以构建应用包，如下一节所述。

使用 bundletool 构建您的应用包

要构建应用包，请使用 bundletool build-bundle 命令，如下所示

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

下表更详细地描述了 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 版本进行转换和合并。

例如，您可以控制启用或禁用哪些类别的配置 APK。以下是一个 BundleConfig.json 文件的示例，它会禁用每个目标语言不同的配置 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 文件中配置的内容的完整说明，请检查使用 Proto3 语法编写的 bundletool config.proto 文件。

从应用包部署您的应用

如果您已构建并签署应用包，请使用 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

上述示例会提示您输入密钥库和密钥的密码，以及密钥的“Distinguished Name”字段。然后，它会生成一个名为 my-release-key.jks 的密钥库文件，并将其保存在当前目录中（您可以将其移动到任何您喜欢的位置）。该密钥库包含一个有效期为 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

    此示例在将 APK 与存储在单个 KeyStore 文件：my-release-key.jks 中的私钥和证书签名后，在 my-app-release.apk 输出签名后的 APK。

    apksigner 工具支持其他签名选项，包括使用单独的私钥和证书文件签署 APK 文件，以及使用多个签名者签署 APK。如需了解更多详情，请参阅 apksigner 参考。

    注意：要使用 apksigner 工具，您必须安装 Android SDK Build Tools 的修订版 24.0.3 或更高版本。您可以使用SDK 管理器更新此软件包。

  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
            ...
        }
    }
}

现在，当您通过调用 Gradle 任务构建应用时，Gradle 会为您签署应用（并运行 zipalign）。

此外，由于您已使用签名密钥配置了 release 构建，因此该构建类型可以使用“install”任务。因此，您可以使用 installRelease 任务在模拟器或设备上构建、对齐、签名和安装 release APK。

使用您的私钥签名的应用已准备好分发，但您应首先阅读有关如何发布您的应用以及查看Google Play 发布清单。