Android AAB手动打包全指南：命令行出包与签名验证详解

先说结论：AAB 手动打包这事，平时不常用，但一旦遇到必须用命令行出包的场景，你会发现网上能讲清楚的文章真没几篇。我不是说那些一键打包的教程没用，而是很多人没意识到，手动打包的核心价值在于“可控”——你清楚每一步发生了什么，也就能在出问题时最快定位到根因。这篇文章就把我用命令行手动打包 AAB 的完整流程、签名校验、常见报错一次性讲透，步骤都是实测过的，可以直接照着抄。

1. 先搞清楚：AAB 和 APK 到底差在哪

很多刚接触 Android 打包的读者会问一个问题：“我直接打 APK 不就行了吗？为什么非要搞 AAB？”这个问题问得很关键，不理解这个，后面看打包命令都是懵的。

1.1 为什么 Google Play 强制推 AAB

从 2021 年 8 月开始，Google Play 就要求新应用必须使用 AAB 格式上架了。所谓 AAB，全称是 Android App Bundle，它不是一个可以直接安装到手机上的安装包，而是一种“发布格式”。你把它上传到 Google Play 后台后，Google 会根据用户的设备配置（屏幕密度、CPU 架构、语言等）动态生成对应的 APK，这叫“分发型 APK”（split APKs）。

打个比方，你开了一家自助餐厅，AAB 是你的中央厨房，备好了所有菜品的原材料；Google Play 是这个餐厅的配餐台，它根据每个客人的口味偏好，只把客人爱吃的菜装盘递出去。客人不需要背着一整包的原材料走。

这样做的好处是用户下载的安装包体积会明显变小。比如你的应用同时支持 armeabi-v7a、arm64-v8a、x86 三种 CPU 架构，还带多套语言资源和多套屏幕密度资源，全部塞进一个 APK 里可能 80MB，但 AAB 分发后用户实际下载的可能只有 40MB 左右。省流量、省存储空间，安装转化率也会高一些，这对开发者来说都是实打实的好处。

1.2 什么时候才需要“手动”打包

虽然 Android Studio 的 Build > Generate Signed App Bundle 菜单点几下就能出包，但手动打包依然有它的应用场景：

• 持续集成服务器（CI）上没法弹图形界面，只能用命令行跑 Gradle 任务。
• 你手头只有一台远程 Linux 服务器，需要通过 SSH 操作完成出包。
• 团队里脚本化构建需求多，需要把打包、签名、重命名、上传这些步骤串成一条流水线。
• Android Studio 本身出了问题，Gradle 缓存也乱了，你需要在命令行里做一次彻底的 clean 和 rebuild。

所以“手动打包”不是要替代 Android Studio 图形化操作，而是让你在必须脱离 IDE 时，依然能打出稳定可用的正式包。这篇文章所有命令都是在 macOS 终端和 Ubuntu 服务器上实测过的，Windows 用户把./gradlew换成gradlew.bat即可。

2. 动手前的准备工作：环境与版本对齐

手动打包最忌讳的就是环境不统一。很多诡异报错，比如Gradle sync failed、Unsupported class file major version，追根溯源都是本地 JDK 版本和 Gradle 版本不匹配造成的。所以正式开始之前，先把环境对齐这件事做好。

2.1 JDK、Gradle、Android SDK 版本怎么定

我先给你一张我用下来比较稳定的搭配表，如果你的项目 AGP 版本不是特别老，直接参考这套问题不大：

注意一点，JDK 版本不是越新越好。JDK 21 我试过，AGP 8.1 以下的项目跑起来会直接报错，因为 AGP 内部依赖的一些库还没跟上。反过来，JDK 8 编译新项目又会因为Unsupported major version失败。所以如果项目已经升到 AGP 8.x，JDK 17 是当前最稳妥的选择。

2.2 检查 gradle-wrapper.properties 和 build.gradle

手动打包之前，我习惯先看两个文件。

第一个是gradle/wrapper/gradle-wrapper.properties，确认distributionUrl指向的 Gradle 版本。

distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip networkTimeout=10000 validateDistributionUrl=true zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists

第二个是项目根目录或app模块下的build.gradle，确认 AGP 版本。通常在根目录的build.gradle里能看到：

plugins { id 'com.android.application' version '8.1.0' apply false }

如果你是在 Android Studio 里点击“Sync Now”总是失败的地方，很可能是 Gradle 版本和 AGP 版本不匹配。这里给一个官方版本对照表的简化版，足够你排查大多数问题：

2.3 准备签名文件与 keystore 信息

AAB 打包需要一个签名文件，一般是.jks或.keystore后缀。如果你还没有这个文件，用keytool命令生成一个，这是 JDK 自带的工具，无需额外安装：

keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release

执行过程中会让你设置密钥库密码、确认个人信息，最后生成release.jks。这个文件务必妥善保管，丢了就相当于你失去了对这个应用的更新权限。我见过有人把 jks 文件放在 Git 仓库里，这种方式坚决不推荐，后面第三节我会专门讲怎么处理签名信息的安全性。

打包前你还需要确认这几项信息：storeFile（jks 文件路径）、storePassword（密钥库密码）、keyAlias（别名）、keyPassword（别名密码）。如果没有这些，后面配置signingConfig就会卡壳。

3. 签名配置与手工加固

签名是 AAB 打包的重中之重。一个没签名的 AAB 是无法被 Google Play 接受的，而且 Android 系统对签名方案的校验也变得越来越严格。

3.1 三种签名方式对比

手动打包时签名方式可以分成三种：在 Gradle 里配置signingConfigs、打包后单独用apksigner签名、以及用旧版jarsigner签名。我把它们的区别列出来：

这里要特别强调 v1、v2、v3 签名方案的区别。v1 是基于 JAR 签名的，对 APK 内的每个文件做校验，老系统兼容性好，但存在安全隐患，而且校验速度慢。v2 是 Android 7.0 引入的，对整个 APK 文件做二进制校验，安全性和校验速度都更好。v3 在 Android 9.0 上引入了密钥轮转功能，允许应用更新时更换签名密钥而不丢失设备上的数据。

如果你的应用minSdkVersion大于等于 24，完全可以只用 v2 及以上签名方案，APK 体积还能略微减小。如果你的minSdkVersion低于 24，那必须同时支持 v1 和 v2，否则老系统装不上。

3.2 在 build.gradle 里配好 signingConfig

我平时最常用的做法是在app/build.gradle里定义一个signingConfigs，然后把bundleRelease任务挂上签名。示例配置如下：

android { signingConfigs { release { storeFile file("../../keystore/release.jks") storePassword "yourStorePassword" keyAlias "release" keyPassword "yourKeyPassword" } } buildTypes { release { minifyEnabled true shrinkResources true proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' signingConfig signingConfigs.release } } }

这段配置里两个容易被忽视的点，我先提一下。

第一，minifyEnabled true会开启代码混淆，shrinkResources true会移除未使用的资源。这对正式包很重要，但也意味着如果你的 ProGuard 规则不完整，打包后可能会出现运行时类找不到的崩溃。后面第 6 节我会单独讲这个问题。

第二，storePassword和keyPassword直接写在build.gradle里有泄露风险。如果项目仓库是私有且只有你自己维护，图省事直接写问题不大。但只要是团队项目，我建议把密码改成从环境变量读取：

storePassword System.getenv("STORE_PASSWORD") keyPassword System.getenv("KEY_PASSWORD")

然后在打包前用export命令设置环境变量，密码就不会进入版本控制历史了。

3.3 jks 文件泄露的风险控制

关于签名文件的保存，我分享几条实际项目里总结出来的经验：

• jks 文件不要提交到 Git、SVN、GitLab 等任何版本控制仓库，即使仓库是私有的也不行，仓库权限经常比你想的宽。
• jks 文件建议单独放在keystore/目录并加入.gitignore，与源码隔离。
• 正式的发布密钥至少准备两份备份，分别存放在不同介质上，比如一台离线电脑和一个加密 U 盘。
• 如果怀疑 jks 泄露，不要心存侥幸试图“续用”，应尽快用新密钥发布新版本并考虑密钥轮转，不过这会带来一定的用户数据影响，所以前期保护更重要。

4. 核心流程：一行命令打出 AAB

环境准备好了，签名配置也完成了，接下来就是真正的打包环节。这一节我会从最基础的命令开始，逐步深入到多模块项目、flavor 打包等实际场景。

4.1 常用任务名与参数说明

Gradle 的打包任务是有规律的，你不需要死记每一个任务名，掌握规律后就很容易举一反三。

对单模块项目，生成 AAB 的核心任务是：

./gradlew bundleRelease

这里的bundle表示要生成 Android App Bundle，Release表示使用 release 构建类型。如果是 debug 包，就是：

./gradlew bundleDebug

如果你项目里配置了 product flavors，比如dev和prod，那么任务名会变成bundleDevRelease和bundleProdRelease。规律就是bundle + 首字母大写的 flavor 名 + 首字母大写的 buildType 名。

打包过程中 Gradle 会先执行一系列前置任务，包括资源编译、Java 编译、混淆、DEX 生成、资源压缩等。第一次打包通常会比较慢，因为需要下载依赖和编译所有模块。

4.2 完整的打包命令与产物核对

我习惯先执行一次 clean 再打包，避免增量编译带来的隐藏问题：

./gradlew clean ./gradlew bundleRelease

如果是 CI 环境，可以把两条命令合并：

./gradlew clean bundleRelease

打包完成后，AAB 文件的默认输出路径是：

app/build/outputs/bundle/release/app-release.aab

如果你配置了applicationId为com.example.myapp，文件名还是app-release.aab，不会自动加上包名，需要重命名的话可以手动复制一份。

我做完打包后的第一件事就是用ls -lh查看文件大小，大致判断产物是否正常：

ls -lh app/build/outputs/bundle/release/app-release.aab

正常情况一个中大型应用的 AAB 文件在 20MB 到 80MB 之间。如果你发现文件特别小，比如只有几百 KB，那要警惕是不是代码被混淆掉了很多，或者某些资源没有被正常打包进去。这时候需要去app/build/outputs/mapping/release/目录查看混淆日志，确认关键类和方法是否还在。

4.3 多模块项目的 flavor 打包

规模大一点的项目通常会有多个模块，比如:app、:core、:network、:feature_home，同时还会配置多个 flavor。这种情况下手动打包的命令会稍有不同。

假设 project 里有app和core两个模块，flavor 维度有dev和prod，你只需要在根目录执行：

./gradlew :app:bundleProdRelease

任务名前加了模块路径:app:，Gradle 会帮你自动处理所有依赖模块。比如:app依赖:core，那么:core也会以prod和release对应的变体参与编译。

这里要特别提醒一个多模块打包常见的坑：如果你的某个子模块没有配置proguardFiles，而主模块开启了混淆，子模块里的代码可能会在混淆阶段被处理，导致某些通过反射调用的类找不到报错。所以多模块项目里，建议把公共的混淆规则统一放到主模块的proguard-rules.pro中，子模块只保留自己特有的规则。

5. 没有 Android Studio 也能完成签名验证

打完包还没结束。很多人在本机用 Android Studio 打包、上传、上架一路顺风顺水，但一到手动打包就卡在了“这 AAB 到底能不能装、签名到底对不对”的验证环节。其实完全可以在命令行里完成这套检查，并不需要打开 IDE。

5.1 用 bundletool 从 AAB 生成 APKS

AAB 不能直接安装到设备，这是它的格式决定的。Google 官方提供了一个命令行工具叫bundletool，它负责把 AAB 转换成设备可识别的 APK 集合。这个工具你可以在 Google 的 Maven 仓库下载到 jar 包，然后用 Java 运行。

把 AAB 转换成可安装 APK 集合的命令如下：

java -jar bundletool-all-1.15.6.jar build-apks \ --bundle=app-release.aab \ --output=app-release.apks \ --ks=release.jks \ --ks-pass=pass:yourStorePassword \ --ks-key-alias=release \ --key-pass=pass:yourKeyPassword

这里--ks指定签名文件，--ks-pass传入密钥库密码，--ks-key-alias指定别名，--key-pass传入别名密码。参数含义和 Gradle 配置里的storeFile、storePassword、keyAlias、keyPassword一一对应。

生成的文件后缀是.apks，它并不是一个普通 zip，而是一个 APK 集合的容器，里面可能包含多个 split APK。注意，这个步骤同时也在对 AAB 进行签名验证，如果签名配置有误，这里就会直接报错。

5.2 单独提取 universal APK

.apks文件生成后，如果你想安装到本地设备做冒烟测试，有两种方式。

第一种是直接用 bundletool 安装连接好的设备：

java -jar bundletool-all-1.15.6.jar install-apks --apks=app-release.apks

第二种是先从.apks中提取一个通用 APK（universal APK），这个 APK 包含所有资源，相当于传统意义上的完整 APK，然后传给同事或者手动安装：

java -jar bundletool-all-1.15.6.jar extract-apks \ --apks=app-release.apks \ --output-dir=./extracted \ --device-spec=device-spec.json

这里--device-spec可以指定设备配置，如果你不指定，bundletool 会尝试连接一台在线设备并读取配置。如果只想提取所有设备通用的那个 APK，可以试试：

unzip -o app-release.apks -d apks_output

解压后你会看到一个universal.apk，这个就是包含全部资源的完整 APK。直接把它传到手机上就能安装。

5.3 验证签名与安装到设备

用apksigner可以查看 AAB 或 APK 的签名详情，这个工具在 Android SDK 的build-tools目录下：

$ANDROID_HOME/build-tools/34.0.0/apksigner verify --print-certs app-release.aab

如果输出里有Signer #1 certificate DN: CN=...这样的信息，并且Verified using v2 scheme: true，说明签名没问题。如果显示DOES NOT VERIFY或Verified using v1 scheme: true而 v2 是 false，你就要根据第一节说的 minSdkVersion 情况判断是否合规。

6. 我踩过的坑：常见错误与排查实录

这一节是我最想写的部分。手动打包不像 Android Studio 图形化操作那么“友好”，遇到问题的话报错信息往往很裸，但其实就是那几类问题，排查思路是固定的。

6.1 Execution failed for task ':app:bundleRelease'

这是最常见的报错，没有之一。报错信息后面通常还会跟着一句Execution failed for task ':app:packageReleaseBundle'或类似的字眼。出现这个问题，我建议按以下顺序排查：

• 看日志中是否出现AAPT2 error。如果是，基本是资源文件有问题。常见的场景是某个图片资源用了中文命名、XML 布局里有非法字符、或者 values 目录下的字符串资源有格式错误。逐个检查报错里提示的文件路径，通常能发现线索。
• 看是否出现Duplicate resources。这通常是因为多个模块依赖了同一个库的不同版本，或者res目录下存在同名资源。在build.gradle里显式排除冲突依赖即可。
• 看是否出现Failed to transform ...。这类问题大多与依赖下载失败或缓存损坏有关。先试试清除 Gradle 缓存再重试：

./gradlew clean ./gradlew bundleRelease --refresh-dependencies

如果还不行，删掉用户目录下的.gradle/caches目录，让 Gradle 全量重新下载依赖，问题大概率解决。

6.2 Signature scheme V2 缺失导致上架失败

这种情况比较隐蔽。你在本地打包后上传到 Google Play Console，系统提示 APK Signature Scheme v2 缺失或者签名无效，但你在 Android Studio 里打包却一切正常。

出现这个差异的原因通常是你本地手动打包时用了旧版jarsigner，而jarsigner只生成 v1 签名。解决办法是改用apksigner对 AAB 进行签名，或者在 Gradle 配置中确认signingConfig用的是正确的密钥。验证方法就是我上节写的apksigner verify --print-certs，看完输出就知道问题出在哪了。

6.3 混淆规则漏配导致的崩溃

我在第 3 节提到过，minifyEnabled true开启后，如果 ProGuard 规则不全，打包出来的应用会在运行时崩溃。最常见的现象是：安装没问题、启动闪退，Logcat 里出现ClassNotFoundException或者NoSuchMethodException。

排查思路并不复杂。先看混淆日志app/build/outputs/mapping/release/mapping.txt，找到报错类在混淆前的全限定名，然后确认是否被错误的重命名了。如果是你自己写的类，在proguard-rules.pro里加-keep规则即可：

-keep class com.yourpackage.yourmodule.** { *; }

如果报错的是第三方 SDK 的类，优先去对应 SDK 的官方文档找它提供的 ProGuard 配置，通常是一段可以直接贴到proguard-rules.pro的规则。不要不加思考地-keep整个依赖，那样会失去混淆的意义，APK 体积也会变大。

6.4 版本号与 versionCode 冲突

手动打包时另一个容易踩的坑是 versionCode 没改，导致上传到 Google Play 时提示版本号冲突。Android Studio 的 Release 构建菜单会在构建前检查这个问题，但是命令行打包没有这个前置检查，你很容易带着同一个 versionCode 打出两个包。

解决方法是每次手动打包前检查app/build.gradle里的versionCode，或者用脚本在 CI 里自动递增：

def versionCode = (System.getenv("CI_PIPELINE_ID") ?: 1) as Integer

6.5 打包慢与内存溢出的处理

一个大项目首次打包耗时 10 分钟以上很常见。如果你的服务器内存比较小，可能会出现Daemon is stopping immediately due to memory pressure或者GC overhead limit exceeded之类的错误。

可以在项目根目录的gradle.properties里调大 Gradle JVM 内存：

org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g -Dfile.encoding=UTF-8

如果需要进一步加快构建速度，考虑开启构建缓存和并行执行：

org.gradle.caching=true org.gradle.parallel=true

不过我实测下来，并行执行在模块依赖比较复杂时反而可能因为资源竞争导致某几个模块的编译时间增加，所以如果你的项目模块数不多，保持默认串行反而更稳。手动打包到这个阶段，你已经可以脱离 Android Studio 完成从源码到成品的全部工作了，剩下的就是把这些命令串成脚本、接入到你的 CI 流程里，让出包变成一件不再依赖人工的重复劳动。