从命令行构建您的应用

您可以使用 Gradle 包装器 命令行工具执行 Android 项目可用的所有构建任务。它以 Windows 的批处理文件 (gradlew.bat) 和 Linux 和 Mac 的 shell 脚本 (gradlew.sh) 的形式提供，并且可以从使用 Android Studio 创建的每个项目的根目录访问。

要使用包装器运行任务，请从终端窗口中使用以下命令之一（从 Android Studio 中，选择**查看 > 工具窗口 > 终端**）

  • 在 Windows 命令提示符下
    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

上述任务名称中的“Debug”只是 构建变体名称的驼峰式版本，因此可以将其替换为您要组装或安装的任何构建类型或变体。例如，如果您有一个“demo”产品风格，则可以使用 assembleDemoDebug 任务构建调试版。

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

另请参阅有关如何在 模拟器上运行应用 和 设备上运行应用 的部分。

构建发布版应用包或 APK

当您准备好发布和分发应用时，必须构建一个使用您的私钥签名的发布包或 APK。有关更多信息，请转到关于如何从命令行签署应用的章节从命令行签署您的应用。

将您的应用部署到模拟器

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

拥有 AVD 后，请按如下方式启动 Android 模拟器并安装您的应用

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

    emulator -avd avd_name

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

  2. 现在，您可以使用“构建调试 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 调试**。您可以在**设置 > 开发者选项**下找到此选项。

注意：在 Android 4.2 及更高版本中，**开发者选项**默认情况下处于隐藏状态。要使其可用，请转到**设置 > 关于手机**，然后点击**内部版本号**七次。返回到上一个屏幕以查找**开发者选项**。

设备设置完毕并通过 USB 连接后，您可以使用“构建调试 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 任务。例如，以下命令会为基础模块的调试版本构建一个应用包

./gradlew :base:bundleDebug

如果您想构建一个签名的包以上传到 Play 控制台，则需要先使用应用的签名信息配置基础模块的build.gradle.kts文件。要了解更多信息，请转到关于如何配置 Gradle 以签署您的应用的章节。然后，例如，您可以构建应用的发布版本，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文件扩展名。Protobufs 提供了一种与语言无关、与平台无关且可扩展的序列化结构化数据机制 - 它类似于 XML，但更小、更快且更简单。

下载 AAPT2

您可以使用来自Google Maven 存储库的最新版本的 AAPT2 生成应用的清单文件和资源表，并将其以 protobuf 格式显示。

要从 Google 的 Maven 存储库下载 AAPT2，请按如下操作

  1. 在存储库索引中导航到**com.android.tools.build > aapt2**。
  2. 复制最新版本 AAPT2 的名称。

  3. 将复制的版本名称插入以下 URL 并指定您的目标操作系统：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. 在浏览器中导航到该 URL - 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 中，指示 AAPT2 将应用的清单和已编译的资源转换为 protobuf 格式，方法是包含--proto-format标志，如下所示

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 版本并将其与每个应用包中包含的 protobuf 版本合并。

例如，您可以控制要启用或禁用的配置 APK 类别。以下 BundleConfig.json 文件示例禁用每个目标不同语言的配置 APK（即，所有语言的资源都包含在其各自的基本或功能 APK 中）

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

在您的 BundleConfig.json 文件中，您还可以指定在使用 APK 打包时哪些文件类型保持未压缩状态 glob 模式，如下所示

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

请记住，默认情况下，bundletool 不会压缩您的应用的原生库（在 Android 6.0 或更高版本上）和资源表（resources.arsc）。有关您可以在 BundleConfig.json 中配置的内容的完整说明，请检查 bundletool config.proto 文件，该文件使用 Proto3 语法编写。

从应用包部署您的应用

如果您已构建并签署了应用包，请使用 bundletool 生成 APK 并将其部署到设备。

从命令行签署您的应用

您不需要 Android Studio 来签署您的应用。您可以使用命令行签署您的应用，对于 APK 使用 apksigner，对于应用包使用 jarsigner，或者配置 Gradle 在构建过程中为您签署。无论哪种方式，您都需要首先使用 keytool 生成私钥，如下所示

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

以上示例会提示您输入密钥库和密钥的密码，以及密钥的“识别名称”字段。然后，它会将密钥库生成名为 my-release-key.jks 的文件，并将其保存在当前目录中（您可以将其移动到任何您想要的位置）。密钥库包含一个有效期为 10,000 天的密钥。

现在，您可以手动签署您的 APK 或应用包，或配置 Gradle 在构建过程中签署您的应用，如以下部分所述。

从命令行手动签署您的应用

如果要从命令行签署应用包，可以使用 jarsigner。如果要签署 APK，则需要使用 zipalign 和 apksigner，如下所述。

  1. 打开命令行 - 从 Android Studio 中，选择查看 > 工具窗口 > 终端 - 并导航到未签署的 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

    此示例在使用存储在单个密钥库文件 my-release-key.jks 中的私钥和证书签署后，将签名的 APK 输出到 my-app-release.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）。

此外，因为您已使用签名密钥配置了发布构建，所以该构建类型可使用“安装”任务。因此，您可以使用 installRelease 任务构建、对齐、签署并在模拟器或设备上安装发布版 APK。

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