1. 项目概述从APK到AAB一次打包流程的深度演进如果你是一名Android开发者最近一年肯定被Google Play商店的一个新要求“刷屏”了自2021年8月起新应用必须使用Android App BundleAAB格式发布。这个变化让很多习惯了直接生成APK文件上传的开发者尤其是中小团队和个人开发者感到了一丝困惑和阵痛。AAB到底是什么它和传统的APK有何不同更重要的是我们日常的开发、调试、测试流程该如何适应这种新的打包格式简单来说AAB不是一个可以直接安装到手机上的文件而是一个“发布包”或“中间包”。你可以把它理解为一个包含了你的应用所有代码、资源、原生库的“原材料仓库”。当用户从Google Play下载你的应用时商店会根据用户设备的特定配置如屏幕密度、CPU架构、语言从这个“仓库”里精准地挑选出需要的部分动态生成一个最优化的、体积更小的APK文件给用户安装。这个过程被称为“动态交付”。因此AAB带来的最直接好处就是显著的安装包体积缩减这对于提升用户下载转化率和节省用户存储空间至关重要。然而从开发者的视角来看AAB的引入不仅仅是换一个文件格式那么简单。它深刻地改变了我们构建、测试和分发应用的整个工作流。传统的assembleRelease生成一个通用APK就能覆盖所有测试场景的日子一去不复返了。现在我们需要理解如何构建AAB、如何从AAB中提取出针对特定设备的APK用于本地测试、如何在Android Studio中直接调试基于AAB配置的应用以及如何处理那些因AAB特性如Play Feature Delivery而变得复杂的安装逻辑。本文将从一个一线开发者的角度彻底拆解Android AAB的打包、调试与安装全流程分享从项目配置到上架前测试的完整实战经验与避坑指南。2. AAB打包全流程解析与配置实战2.1 基础环境与Gradle配置要点在开始打包AAB之前确保你的开发环境已经就绪。你需要使用Android Studio 3.2或更高版本并且对应的Android Gradle插件AGP版本也需要在3.2.0以上。我强烈建议使用当前稳定的最新版本因为Google在AAB和构建工具链上持续进行着优化。打包AAB的核心配置都在你的模块级build.gradle文件中。与生成APK不同你不再需要配置复杂的productFlavors和splits来手动分割不同ABI或密度的资源当然特殊需求除外。AAB的构建系统会自动处理这些。你的配置重点应该转向如何优化构建产物以及如何启用AAB的高级特性。首先在android块中确保bundle块被正确配置。bundle块是控制AAB生成行为的核心。android { // ... 其他配置如compileSdkVersion等 buildTypes { release { minifyEnabled true proguardFiles getDefaultProguardFile(proguard-android-optimize.txt), proguard-rules.pro // 签名配置通常在根目录的gradle.properties或单独文件中管理 } } // AAB相关配置 bundle { language { // 启用语言拆分。默认true将为每种语言生成独立的资源包。 enableSplit true } density { // 启用屏幕密度拆分。默认true将为不同密度生成独立的资源包。 enableSplit true } abi { // 启用ABICPU架构拆分。默认true将为每种ABI生成独立的原生库包。 enableSplit true } } }注意enableSplit true是默认行为意味着AAB构建时会自动为语言、密度和ABI生成独立的模块称为“Split APKs”的基础。这直接带来了体积节省。除非你有特殊理由例如你的应用必须强制包含所有语言资源否则不要将其设为false。接下来是签名。AAB的签名至关重要因为它关系到应用在Play商店的认证和后续更新。绝对不要将签名密钥keystore和密码硬编码在build.gradle文件中或上传到版本控制系统。标准做法是使用环境变量或单独的属性文件。在项目根目录创建keystore.properties文件并加入.gitignorestorePasswordyour_keystore_password keyPasswordyour_key_password keyAliasyour_key_alias storeFile/path/to/your/upload-keystore.jks在模块级build.gradle中读取并配置签名// 读取keystore.properties def keystorePropertiesFile rootProject.file(keystore.properties) def keystoreProperties new Properties() if (keystorePropertiesFile.exists()) { keystoreProperties.load(new FileInputStream(keystorePropertiesFile)) } android { signingConfigs { release { keyAlias keystoreProperties[keyAlias] keyPassword keystoreProperties[keyPassword] storeFile keystoreProperties[storeFile] ? file(keystoreProperties[storeFile]) : null storePassword keystoreProperties[storePassword] } } buildTypes { release { signingConfig signingConfigs.release } } }2.2 执行打包命令与产物分析配置完成后生成AAB文件非常简单。在Android Studio中你可以通过菜单Build Generate Signed Bundle / APK...然后选择Android App Bundle按照图形界面向导完成。但对于自动化构建如CI/CD流水线命令行方式更常用。打开终端进入项目根目录执行以下命令./gradlew :app:bundleRelease如果你的应用模块名称不是app请替换为对应的模块名例如:yourModuleName:bundleRelease。命令执行成功后你可以在app/build/outputs/bundle/release/目录下找到生成的app-release.aab文件。这个文件就是你要上传到Google Play控制台的最终发布包。深入理解AAB文件结构AAB文件本质上是一个Zip压缩包。你可以将其后缀改为.zip后解压一窥其内部结构。关键目录包括BUNDLE-METADATA/: 包含构建元数据。base/: 这是应用的“基础模块”包含了所有设备都必须的代码和资源如classes.dex,AndroidManifest.xml, 共享资源等。manifest/: 存储了整个Bundle的清单信息。res/,lib/,assets/等这些目录在base和可能的特性模块中按需存放资源。如果配置了动态功能模块Dynamic Feature Module还会看到以模块名命名的目录如feature1/。与单一的、庞大的APK文件相比AAB的这种模块化结构正是其实现“动态交付”的物理基础。Play商店就像一个大厨根据顾客用户设备的点单配置从这些分门别类准备好的食材模块中快速组合出一份定制化的餐点APK。2.3 高级特性动态功能模块配置AAB的强大之处在于支持动态功能模块。这允许你将应用的某些功能拆分成独立的模块用户可以在安装后按需下载实现功能的“即时交付”或“条件交付”。这对于制作大型应用如游戏、包含大量教育视频的应用非常有用。创建动态功能模块在Android Studio中File New New Module。选择Dynamic Feature Module。配置模块名称、包名等。关键一步是选择Enable on-demand按需交付和Fusing是否包含在免安装体验或Android旧版本中。如果该功能对应用核心体验不是立即必需的通常选择按需交付。配置模块间的依赖在你的基础模块通常是app的build.gradle中需要声明对动态功能模块的依赖但使用dynamicFeatures属性。// 在app模块的build.gradle中 android { dynamicFeatures [:feature1, :feature2] }同时在动态功能模块的build.gradle中需要依赖基础模块// 在feature1模块的build.gradle中 dependencies { implementation project(:app) }在代码中请求安装动态模块这是动态功能的核心。使用Play Core库。// 1. 添加依赖在基础模块的build.gradle中 implementation \com.google.android.play:core:1.10.3\ // 2. 创建SplitInstallManager private val splitInstallManager by lazy { SplitInstallManagerFactory.create(context) } // 3. 请求安装模块 fun installFeatureModule(moduleName: String) { val request SplitInstallRequest.newBuilder() .addModule(moduleName) // 例如 \feature1\ .build() splitInstallManager.startInstall(request) .addOnSuccessListener { sessionId - // 安装请求已接收 } .addOnFailureListener { exception - // 处理失败 } } // 4. 监听安装状态通常通过一个前台Service或BroadcastReceiver实操心得动态模块的安装需要网络连接且用户可能会拒绝或暂停下载。你的应用UI必须能优雅地处理这些中间状态下载中、等待网络、用户取消等。Google提供了SplitInstallStateUpdatedListener来监听状态变化务必实现完整的用户体验流。3. 本地调试与测试从AAB到可安装APK生成的.aab文件不能直接安装到手机上进行测试。为了在本地验证AAB的构建是否正确以及测试动态功能我们需要借助两个关键工具bundletool和Android Studio的内部机制。3.1 使用bundletool生成特定设备APK集bundletool是Google官方提供的用于构建和操作AAB的命令行工具。它最重要的功能之一就是从AAB文件生成针对特定设备配置的APK集一组APK文件并安装到设备。第一步下载bundletool。你可以从Google的Maven仓库下载最新的jar包。第二步生成设备规格JSON文件。为了生成匹配你测试设备的APK需要先获取设备的规格。# 连接你的Android设备或启动模拟器 adb devices # 获取设备规格保存到device-spec.json java -jar bundletool-all.jar get-device-spec --outputdevice-spec.json这个device-spec.json文件描述了设备的屏幕密度、支持的ABI、语言等参数。第三步从AAB生成APK集。java -jar bundletool-all.jar build-apks \ --bundleapp/build/outputs/bundle/release/app-release.aab \ --outputapp/build/outputs/bundle/release/app-release.apks \ --ks/path/to/your/keystore.jks \ --ks-passpass:your_keystore_password \ --ks-key-aliasyour_key_alias \ --key-passpass:your_key_password \ --device-specdevice-spec.json这条命令会生成一个.apks文件它是一个包含了一组APK基础APK、配置APK等的Zip包专门针对你指定的设备。第四步安装APK集到设备。java -jar bundletool-all.jar install-apks --apksapp/build/outputs/bundle/release/app-release.apksbundletool会自动将正确的APK组合安装到已连接的设备上。这是最接近从Play商店安装的本地测试方式。3.2 Android Studio内置调试支持对于日常开发调试每次都使用bundletool命令行太繁琐。Android Studio提供了更便捷的方式。使用“Edit Configurations”直接调试AAB配置在Android Studio中点击运行配置下拉菜单选择Edit Configurations...。在General标签页下找到Deploy部分。在Deploy下拉框中默认是APK from app bundle。这意味着当你点击运行时Android Studio会 a. 在后台为你当前连接的设备构建一个优化的AAB或使用最近的构建缓存。 b. 自动从中提取出匹配该设备的APK集。 c. 安装并运行。你还可以勾选下方的Dynamic features to deploy选择要包含在本次部署中的动态功能模块即使它们被标记为on-demand。这对于测试动态模块的功能是否正常集成非常有用。这种方式让你在开发带有动态功能的应用时可以像调试普通应用一样设置断点、查看日志而无需关心底层的APK生成细节。Profile或Debug APK当你需要分析性能或内存时可以生成一个针对你设备的、可调试的APK集。在终端运行./gradlew :app:assembleDebug这仍然会生成一个完整的、未优化的APK因为AAB的优化主要针对Release版本。对于涉及原生库或资源拆分的深度调试还是需要借助bundletool从Release版AAB生成测试包。3.3 模拟多设备测试与离线测试包在发布前你需要确保AAB在各种主流设备配置上都能正确生成和安装APK。bundletool的get-size命令可以模拟计算在不同设备上安装后的应用大小但这不涉及实际安装。为了进行更全面的安装测试你可以生成一个通用APK集Universal APK它包含了所有配置的代码和资源因此体积巨大仅用于测试安装流程和核心功能不应发布。java -jar bundletool-all.jar build-apks \ --bundleapp-release.aab \ --outputapp-release-universal.apks \ --modeuniversal \ --ks... # 签名信息同上然后使用install-apks安装这个.apks文件。这个Universal APK在功能上等同于从AAB生成的最大化APK可以用来验证应用逻辑是否正确。此外对于需要分发给测试团队进行内部测试的场景不通过Play商店你可以利用Google Play的“内部测试轨道”上传AAB测试人员通过链接加入测试来安装。对于完全离线的场景则可以生成多个针对不同设备规格的.apks文件分发给测试人员他们再用bundletool安装。4. 安装流程剖析与Play商店集成4.1 动态交付安装流程详解当用户从Google Play商店点击安装你的应用AAB格式时背后发生了一系列精密的操作设备信息上报用户的设备向Play商店发送其硬件和软件配置信息包括屏幕密度dpi、CPU架构ABI如arm64-v8a, armeabi-v7a, x86等、系统语言和区域。商店端处理Play商店服务器接收到你的.aab文件和设备配置信息。bundletool的服务器端版本开始工作根据设备配置从AAB的各个模块中精确筛选出需要的部分从base模块提取所有设备都需要的核心内容。从对应的density、abi、language资源目录中只提取匹配该设备的那一份资源。例如对于xxhdpi屏幕的设备只会下载xxhdpi的图片资源而不会下载mdpi或xxxhdpi的。检查是否有需要条件交付的动态功能模块例如根据用户所在国家/地区决定是否包含某个功能。生成优化APK集服务器动态生成一个最小的、针对该设备优化的APK集合通常是一个基础APK 多个配置APK。这个集合的体积远小于一个包含所有资源的通用APK。下载与安装生成的优化APK集被下载到用户设备Android系统的包安装器PackageInstaller会像安装普通APK一样安装这个APK集合。对于用户和系统来说这看起来就像安装了一个单一的应用。4.2 Play商店后台配置与上传将AAB上传到Google Play控制台的过程与APK类似但有一些关键配置点需要注意应用签名这是最重要的一步。Google Play提供了Play App Signing服务。强烈建议启用它。启用后你将上传用“上传密钥”签名的AABGoogle Play会用更安全的“应用签名密钥”重新为分发签名。这样即使你的“上传密钥”丢失也可以联系Google重置而不会影响已上架的应用。上传AAB在Play控制台的“版本发布”页面直接将生成的.aab文件拖入上传区域。控制台会进行解析并展示此AAB支持的设备范围、预估的下载大小针对不同设备等信息。测试轨道充分利用“内部测试”、“封闭测试”和“开放测试”轨道。你可以先将AAB发布到“内部测试”轨道分享给有限的测试人员验证安装、更新和动态功能是否正常工作然后再推送到生产环境。设备目录排除在AAB模式下你可以在Play控制台中更精细地排除某些设备。例如如果你的应用使用了某个仅支持arm64的第三方原生库你可以排除所有32位ARM设备。这比在APK时代通过abiFilters在代码中控制更加灵活和清晰。4.3 处理安装后更新与动态模块AAB应用的更新机制与APK基本一致但动态功能模块的更新有其特殊性基础应用更新当您上传一个包含基础模块更改的新AAB版本时所有用户都会收到基础应用的更新就像普通APK更新一样。动态模块更新动态功能模块的更新是独立的。您可以在Play控制台中单独更新某个动态模块的代码和资源而无需发布新的基础应用版本。当用户下次触发该模块的下载或应用检查更新时会自动获取最新版本的模块。安装状态管理在你的应用中需要使用Play Core库的SplitInstallManager来查询已安装的动态模块列表(installedModules)并据此决定是否显示相关功能入口。当模块更新后installedModules会反映最新的版本状态。5. 常见问题排查与性能优化实录5.1 打包与构建问题问题1构建AAB时出现“Failed to transform xxx.jar”或资源合并错误。排查这通常是因为依赖库或资源文件存在冲突或兼容性问题。AAB的构建过程对资源合并和代码转换的要求更严格。解决运行./gradlew :app:bundleRelease --stacktrace --info获取更详细的错误日志。检查是否有依赖库包含了重复或冲突的Android资源如string/app_name。使用./gradlew :app:dependencies查看依赖树。尝试升级Android Gradle插件AGP到最新稳定版。许多构建问题在新版本中已被修复。清理构建缓存./gradlew clean。问题2AAB文件体积比预期的APK大很多。排查这是正常现象。AAB是包含所有资源的“母包”而APK是针对特定设备的“子集”。比较对象应该是AAB和通用APKUniversal APK而不是针对某个设备的优化APK。解决使用bundletool get-size命令来估算实际用户下载大小这才是关键指标。java -jar bundletool-all.jar get-size \ --apksapp-release.apks \ --dimensionsSCREEN_DENSITY,ABI # 按屏幕密度和ABI维度查看大小问题3动态功能模块中的代码无法被基础模块调用反之亦然。排查模块间依赖和可见性设置不正确。解决确保在基础模块的build.gradle中正确声明了dynamicFeatures。动态模块中的代码默认对基础模块不可见。如果基础模块需要调用动态模块的类可以考虑使用接口抽象通过反射或依赖注入如Dagger Hilt在运行时绑定。更常见的模式是基础模块定义接口动态模块实现。资源访问动态模块可以访问基础模块的资源但基础模块默认不能访问动态模块的资源。如果必须访问可以考虑将共享资源放在一个公共库模块中。5.2 调试与安装问题问题4通过bundletool install-apks安装失败提示“INSTALL_FAILED_INVALID_APK”。排查生成的.apks文件可能损坏或者签名信息不匹配。解决确认用于生成.apks的签名密钥与AAB的签名密钥完全一致。重新生成AAB和.apks文件确保构建过程无中断。检查设备存储空间是否充足。问题5在Android Studio中调试时动态功能模块的代码修改没有生效。排查Android Studio可能没有正确部署动态模块的更改。解决在运行配置中确保勾选了需要测试的动态模块。尝试Build Clean Project然后Build Rebuild Project。有时需要手动卸载应用然后重新运行。问题6测试动态模块下载时一直卡在“等待WIFI连接”或下载失败。排查Play Core库默认在非WIFI环境下会等待或提示用户。另外可能没有正确处理安装状态回调。解决在请求安装时可以设置SplitInstallRequest允许移动网络下载.addModule(moduleName).setRequiredNetworkType(SplitInstallRequest.REQUIRED_NETWORK_MOBILE)。但请注意用户的数据流量消耗。实现完整的SplitInstallStateUpdatedListener监听SplitInstallSessionStatus的各种状态如REQUIRES_USER_CONFIRMATION,FAILED并给出相应的用户提示。5.3 性能与优化建议优化建议1精细控制资源拆分。虽然默认开启所有拆分是好的但对于某些资源类型如所有设备都必须的启动图、字体文件将其保留在基础模块中可能更高效。你可以通过resConfigs来限制打包的资源类型例如只包含英语和中文android { defaultConfig { resConfigs \en\, \zh\ } }优化建议2关注动态模块的初始化性能。当动态模块首次被下载和安装后其Application和Activity的初始化可能会引起卡顿。考虑将重量级初始化操作异步化或延迟到真正需要时。优化建议3监控与数据分析。利用Google Play的“设备目录”和“Android Vitals”数据观察你的AAB在不同设备类型上的安装成功率、崩溃率和性能表现。如果发现某些特定配置的设备问题突出可以考虑调整资源包含策略或代码兼容性。从APK到AAB的转变是Android应用分发模式的一次重要升级。它要求开发者从“构建一个包”的思维转向“管理一个可定制的应用组件集合”的思维。初期可能会遇到一些工具链和流程上的挑战但一旦适应其带来的体积优化和灵活交付能力对于提升用户体验和应用质量的价值是巨大的。我的经验是尽早将项目迁移到AAB并在CI/CD流水线中集成bundletool进行自动化测试是平滑过渡的关键。
Android AAB打包全流程解析：从配置、调试到Play商店上架实战
发布时间：2026/8/1 3:07:53
1. 项目概述从APK到AAB一次打包流程的深度演进如果你是一名Android开发者最近一年肯定被Google Play商店的一个新要求“刷屏”了自2021年8月起新应用必须使用Android App BundleAAB格式发布。这个变化让很多习惯了直接生成APK文件上传的开发者尤其是中小团队和个人开发者感到了一丝困惑和阵痛。AAB到底是什么它和传统的APK有何不同更重要的是我们日常的开发、调试、测试流程该如何适应这种新的打包格式简单来说AAB不是一个可以直接安装到手机上的文件而是一个“发布包”或“中间包”。你可以把它理解为一个包含了你的应用所有代码、资源、原生库的“原材料仓库”。当用户从Google Play下载你的应用时商店会根据用户设备的特定配置如屏幕密度、CPU架构、语言从这个“仓库”里精准地挑选出需要的部分动态生成一个最优化的、体积更小的APK文件给用户安装。这个过程被称为“动态交付”。因此AAB带来的最直接好处就是显著的安装包体积缩减这对于提升用户下载转化率和节省用户存储空间至关重要。然而从开发者的视角来看AAB的引入不仅仅是换一个文件格式那么简单。它深刻地改变了我们构建、测试和分发应用的整个工作流。传统的assembleRelease生成一个通用APK就能覆盖所有测试场景的日子一去不复返了。现在我们需要理解如何构建AAB、如何从AAB中提取出针对特定设备的APK用于本地测试、如何在Android Studio中直接调试基于AAB配置的应用以及如何处理那些因AAB特性如Play Feature Delivery而变得复杂的安装逻辑。本文将从一个一线开发者的角度彻底拆解Android AAB的打包、调试与安装全流程分享从项目配置到上架前测试的完整实战经验与避坑指南。2. AAB打包全流程解析与配置实战2.1 基础环境与Gradle配置要点在开始打包AAB之前确保你的开发环境已经就绪。你需要使用Android Studio 3.2或更高版本并且对应的Android Gradle插件AGP版本也需要在3.2.0以上。我强烈建议使用当前稳定的最新版本因为Google在AAB和构建工具链上持续进行着优化。打包AAB的核心配置都在你的模块级build.gradle文件中。与生成APK不同你不再需要配置复杂的productFlavors和splits来手动分割不同ABI或密度的资源当然特殊需求除外。AAB的构建系统会自动处理这些。你的配置重点应该转向如何优化构建产物以及如何启用AAB的高级特性。首先在android块中确保bundle块被正确配置。bundle块是控制AAB生成行为的核心。android { // ... 其他配置如compileSdkVersion等 buildTypes { release { minifyEnabled true proguardFiles getDefaultProguardFile(proguard-android-optimize.txt), proguard-rules.pro // 签名配置通常在根目录的gradle.properties或单独文件中管理 } } // AAB相关配置 bundle { language { // 启用语言拆分。默认true将为每种语言生成独立的资源包。 enableSplit true } density { // 启用屏幕密度拆分。默认true将为不同密度生成独立的资源包。 enableSplit true } abi { // 启用ABICPU架构拆分。默认true将为每种ABI生成独立的原生库包。 enableSplit true } } }注意enableSplit true是默认行为意味着AAB构建时会自动为语言、密度和ABI生成独立的模块称为“Split APKs”的基础。这直接带来了体积节省。除非你有特殊理由例如你的应用必须强制包含所有语言资源否则不要将其设为false。接下来是签名。AAB的签名至关重要因为它关系到应用在Play商店的认证和后续更新。绝对不要将签名密钥keystore和密码硬编码在build.gradle文件中或上传到版本控制系统。标准做法是使用环境变量或单独的属性文件。在项目根目录创建keystore.properties文件并加入.gitignorestorePasswordyour_keystore_password keyPasswordyour_key_password keyAliasyour_key_alias storeFile/path/to/your/upload-keystore.jks在模块级build.gradle中读取并配置签名// 读取keystore.properties def keystorePropertiesFile rootProject.file(keystore.properties) def keystoreProperties new Properties() if (keystorePropertiesFile.exists()) { keystoreProperties.load(new FileInputStream(keystorePropertiesFile)) } android { signingConfigs { release { keyAlias keystoreProperties[keyAlias] keyPassword keystoreProperties[keyPassword] storeFile keystoreProperties[storeFile] ? file(keystoreProperties[storeFile]) : null storePassword keystoreProperties[storePassword] } } buildTypes { release { signingConfig signingConfigs.release } } }2.2 执行打包命令与产物分析配置完成后生成AAB文件非常简单。在Android Studio中你可以通过菜单Build Generate Signed Bundle / APK...然后选择Android App Bundle按照图形界面向导完成。但对于自动化构建如CI/CD流水线命令行方式更常用。打开终端进入项目根目录执行以下命令./gradlew :app:bundleRelease如果你的应用模块名称不是app请替换为对应的模块名例如:yourModuleName:bundleRelease。命令执行成功后你可以在app/build/outputs/bundle/release/目录下找到生成的app-release.aab文件。这个文件就是你要上传到Google Play控制台的最终发布包。深入理解AAB文件结构AAB文件本质上是一个Zip压缩包。你可以将其后缀改为.zip后解压一窥其内部结构。关键目录包括BUNDLE-METADATA/: 包含构建元数据。base/: 这是应用的“基础模块”包含了所有设备都必须的代码和资源如classes.dex,AndroidManifest.xml, 共享资源等。manifest/: 存储了整个Bundle的清单信息。res/,lib/,assets/等这些目录在base和可能的特性模块中按需存放资源。如果配置了动态功能模块Dynamic Feature Module还会看到以模块名命名的目录如feature1/。与单一的、庞大的APK文件相比AAB的这种模块化结构正是其实现“动态交付”的物理基础。Play商店就像一个大厨根据顾客用户设备的点单配置从这些分门别类准备好的食材模块中快速组合出一份定制化的餐点APK。2.3 高级特性动态功能模块配置AAB的强大之处在于支持动态功能模块。这允许你将应用的某些功能拆分成独立的模块用户可以在安装后按需下载实现功能的“即时交付”或“条件交付”。这对于制作大型应用如游戏、包含大量教育视频的应用非常有用。创建动态功能模块在Android Studio中File New New Module。选择Dynamic Feature Module。配置模块名称、包名等。关键一步是选择Enable on-demand按需交付和Fusing是否包含在免安装体验或Android旧版本中。如果该功能对应用核心体验不是立即必需的通常选择按需交付。配置模块间的依赖在你的基础模块通常是app的build.gradle中需要声明对动态功能模块的依赖但使用dynamicFeatures属性。// 在app模块的build.gradle中 android { dynamicFeatures [:feature1, :feature2] }同时在动态功能模块的build.gradle中需要依赖基础模块// 在feature1模块的build.gradle中 dependencies { implementation project(:app) }在代码中请求安装动态模块这是动态功能的核心。使用Play Core库。// 1. 添加依赖在基础模块的build.gradle中 implementation \com.google.android.play:core:1.10.3\ // 2. 创建SplitInstallManager private val splitInstallManager by lazy { SplitInstallManagerFactory.create(context) } // 3. 请求安装模块 fun installFeatureModule(moduleName: String) { val request SplitInstallRequest.newBuilder() .addModule(moduleName) // 例如 \feature1\ .build() splitInstallManager.startInstall(request) .addOnSuccessListener { sessionId - // 安装请求已接收 } .addOnFailureListener { exception - // 处理失败 } } // 4. 监听安装状态通常通过一个前台Service或BroadcastReceiver实操心得动态模块的安装需要网络连接且用户可能会拒绝或暂停下载。你的应用UI必须能优雅地处理这些中间状态下载中、等待网络、用户取消等。Google提供了SplitInstallStateUpdatedListener来监听状态变化务必实现完整的用户体验流。3. 本地调试与测试从AAB到可安装APK生成的.aab文件不能直接安装到手机上进行测试。为了在本地验证AAB的构建是否正确以及测试动态功能我们需要借助两个关键工具bundletool和Android Studio的内部机制。3.1 使用bundletool生成特定设备APK集bundletool是Google官方提供的用于构建和操作AAB的命令行工具。它最重要的功能之一就是从AAB文件生成针对特定设备配置的APK集一组APK文件并安装到设备。第一步下载bundletool。你可以从Google的Maven仓库下载最新的jar包。第二步生成设备规格JSON文件。为了生成匹配你测试设备的APK需要先获取设备的规格。# 连接你的Android设备或启动模拟器 adb devices # 获取设备规格保存到device-spec.json java -jar bundletool-all.jar get-device-spec --outputdevice-spec.json这个device-spec.json文件描述了设备的屏幕密度、支持的ABI、语言等参数。第三步从AAB生成APK集。java -jar bundletool-all.jar build-apks \ --bundleapp/build/outputs/bundle/release/app-release.aab \ --outputapp/build/outputs/bundle/release/app-release.apks \ --ks/path/to/your/keystore.jks \ --ks-passpass:your_keystore_password \ --ks-key-aliasyour_key_alias \ --key-passpass:your_key_password \ --device-specdevice-spec.json这条命令会生成一个.apks文件它是一个包含了一组APK基础APK、配置APK等的Zip包专门针对你指定的设备。第四步安装APK集到设备。java -jar bundletool-all.jar install-apks --apksapp/build/outputs/bundle/release/app-release.apksbundletool会自动将正确的APK组合安装到已连接的设备上。这是最接近从Play商店安装的本地测试方式。3.2 Android Studio内置调试支持对于日常开发调试每次都使用bundletool命令行太繁琐。Android Studio提供了更便捷的方式。使用“Edit Configurations”直接调试AAB配置在Android Studio中点击运行配置下拉菜单选择Edit Configurations...。在General标签页下找到Deploy部分。在Deploy下拉框中默认是APK from app bundle。这意味着当你点击运行时Android Studio会 a. 在后台为你当前连接的设备构建一个优化的AAB或使用最近的构建缓存。 b. 自动从中提取出匹配该设备的APK集。 c. 安装并运行。你还可以勾选下方的Dynamic features to deploy选择要包含在本次部署中的动态功能模块即使它们被标记为on-demand。这对于测试动态模块的功能是否正常集成非常有用。这种方式让你在开发带有动态功能的应用时可以像调试普通应用一样设置断点、查看日志而无需关心底层的APK生成细节。Profile或Debug APK当你需要分析性能或内存时可以生成一个针对你设备的、可调试的APK集。在终端运行./gradlew :app:assembleDebug这仍然会生成一个完整的、未优化的APK因为AAB的优化主要针对Release版本。对于涉及原生库或资源拆分的深度调试还是需要借助bundletool从Release版AAB生成测试包。3.3 模拟多设备测试与离线测试包在发布前你需要确保AAB在各种主流设备配置上都能正确生成和安装APK。bundletool的get-size命令可以模拟计算在不同设备上安装后的应用大小但这不涉及实际安装。为了进行更全面的安装测试你可以生成一个通用APK集Universal APK它包含了所有配置的代码和资源因此体积巨大仅用于测试安装流程和核心功能不应发布。java -jar bundletool-all.jar build-apks \ --bundleapp-release.aab \ --outputapp-release-universal.apks \ --modeuniversal \ --ks... # 签名信息同上然后使用install-apks安装这个.apks文件。这个Universal APK在功能上等同于从AAB生成的最大化APK可以用来验证应用逻辑是否正确。此外对于需要分发给测试团队进行内部测试的场景不通过Play商店你可以利用Google Play的“内部测试轨道”上传AAB测试人员通过链接加入测试来安装。对于完全离线的场景则可以生成多个针对不同设备规格的.apks文件分发给测试人员他们再用bundletool安装。4. 安装流程剖析与Play商店集成4.1 动态交付安装流程详解当用户从Google Play商店点击安装你的应用AAB格式时背后发生了一系列精密的操作设备信息上报用户的设备向Play商店发送其硬件和软件配置信息包括屏幕密度dpi、CPU架构ABI如arm64-v8a, armeabi-v7a, x86等、系统语言和区域。商店端处理Play商店服务器接收到你的.aab文件和设备配置信息。bundletool的服务器端版本开始工作根据设备配置从AAB的各个模块中精确筛选出需要的部分从base模块提取所有设备都需要的核心内容。从对应的density、abi、language资源目录中只提取匹配该设备的那一份资源。例如对于xxhdpi屏幕的设备只会下载xxhdpi的图片资源而不会下载mdpi或xxxhdpi的。检查是否有需要条件交付的动态功能模块例如根据用户所在国家/地区决定是否包含某个功能。生成优化APK集服务器动态生成一个最小的、针对该设备优化的APK集合通常是一个基础APK 多个配置APK。这个集合的体积远小于一个包含所有资源的通用APK。下载与安装生成的优化APK集被下载到用户设备Android系统的包安装器PackageInstaller会像安装普通APK一样安装这个APK集合。对于用户和系统来说这看起来就像安装了一个单一的应用。4.2 Play商店后台配置与上传将AAB上传到Google Play控制台的过程与APK类似但有一些关键配置点需要注意应用签名这是最重要的一步。Google Play提供了Play App Signing服务。强烈建议启用它。启用后你将上传用“上传密钥”签名的AABGoogle Play会用更安全的“应用签名密钥”重新为分发签名。这样即使你的“上传密钥”丢失也可以联系Google重置而不会影响已上架的应用。上传AAB在Play控制台的“版本发布”页面直接将生成的.aab文件拖入上传区域。控制台会进行解析并展示此AAB支持的设备范围、预估的下载大小针对不同设备等信息。测试轨道充分利用“内部测试”、“封闭测试”和“开放测试”轨道。你可以先将AAB发布到“内部测试”轨道分享给有限的测试人员验证安装、更新和动态功能是否正常工作然后再推送到生产环境。设备目录排除在AAB模式下你可以在Play控制台中更精细地排除某些设备。例如如果你的应用使用了某个仅支持arm64的第三方原生库你可以排除所有32位ARM设备。这比在APK时代通过abiFilters在代码中控制更加灵活和清晰。4.3 处理安装后更新与动态模块AAB应用的更新机制与APK基本一致但动态功能模块的更新有其特殊性基础应用更新当您上传一个包含基础模块更改的新AAB版本时所有用户都会收到基础应用的更新就像普通APK更新一样。动态模块更新动态功能模块的更新是独立的。您可以在Play控制台中单独更新某个动态模块的代码和资源而无需发布新的基础应用版本。当用户下次触发该模块的下载或应用检查更新时会自动获取最新版本的模块。安装状态管理在你的应用中需要使用Play Core库的SplitInstallManager来查询已安装的动态模块列表(installedModules)并据此决定是否显示相关功能入口。当模块更新后installedModules会反映最新的版本状态。5. 常见问题排查与性能优化实录5.1 打包与构建问题问题1构建AAB时出现“Failed to transform xxx.jar”或资源合并错误。排查这通常是因为依赖库或资源文件存在冲突或兼容性问题。AAB的构建过程对资源合并和代码转换的要求更严格。解决运行./gradlew :app:bundleRelease --stacktrace --info获取更详细的错误日志。检查是否有依赖库包含了重复或冲突的Android资源如string/app_name。使用./gradlew :app:dependencies查看依赖树。尝试升级Android Gradle插件AGP到最新稳定版。许多构建问题在新版本中已被修复。清理构建缓存./gradlew clean。问题2AAB文件体积比预期的APK大很多。排查这是正常现象。AAB是包含所有资源的“母包”而APK是针对特定设备的“子集”。比较对象应该是AAB和通用APKUniversal APK而不是针对某个设备的优化APK。解决使用bundletool get-size命令来估算实际用户下载大小这才是关键指标。java -jar bundletool-all.jar get-size \ --apksapp-release.apks \ --dimensionsSCREEN_DENSITY,ABI # 按屏幕密度和ABI维度查看大小问题3动态功能模块中的代码无法被基础模块调用反之亦然。排查模块间依赖和可见性设置不正确。解决确保在基础模块的build.gradle中正确声明了dynamicFeatures。动态模块中的代码默认对基础模块不可见。如果基础模块需要调用动态模块的类可以考虑使用接口抽象通过反射或依赖注入如Dagger Hilt在运行时绑定。更常见的模式是基础模块定义接口动态模块实现。资源访问动态模块可以访问基础模块的资源但基础模块默认不能访问动态模块的资源。如果必须访问可以考虑将共享资源放在一个公共库模块中。5.2 调试与安装问题问题4通过bundletool install-apks安装失败提示“INSTALL_FAILED_INVALID_APK”。排查生成的.apks文件可能损坏或者签名信息不匹配。解决确认用于生成.apks的签名密钥与AAB的签名密钥完全一致。重新生成AAB和.apks文件确保构建过程无中断。检查设备存储空间是否充足。问题5在Android Studio中调试时动态功能模块的代码修改没有生效。排查Android Studio可能没有正确部署动态模块的更改。解决在运行配置中确保勾选了需要测试的动态模块。尝试Build Clean Project然后Build Rebuild Project。有时需要手动卸载应用然后重新运行。问题6测试动态模块下载时一直卡在“等待WIFI连接”或下载失败。排查Play Core库默认在非WIFI环境下会等待或提示用户。另外可能没有正确处理安装状态回调。解决在请求安装时可以设置SplitInstallRequest允许移动网络下载.addModule(moduleName).setRequiredNetworkType(SplitInstallRequest.REQUIRED_NETWORK_MOBILE)。但请注意用户的数据流量消耗。实现完整的SplitInstallStateUpdatedListener监听SplitInstallSessionStatus的各种状态如REQUIRES_USER_CONFIRMATION,FAILED并给出相应的用户提示。5.3 性能与优化建议优化建议1精细控制资源拆分。虽然默认开启所有拆分是好的但对于某些资源类型如所有设备都必须的启动图、字体文件将其保留在基础模块中可能更高效。你可以通过resConfigs来限制打包的资源类型例如只包含英语和中文android { defaultConfig { resConfigs \en\, \zh\ } }优化建议2关注动态模块的初始化性能。当动态模块首次被下载和安装后其Application和Activity的初始化可能会引起卡顿。考虑将重量级初始化操作异步化或延迟到真正需要时。优化建议3监控与数据分析。利用Google Play的“设备目录”和“Android Vitals”数据观察你的AAB在不同设备类型上的安装成功率、崩溃率和性能表现。如果发现某些特定配置的设备问题突出可以考虑调整资源包含策略或代码兼容性。从APK到AAB的转变是Android应用分发模式的一次重要升级。它要求开发者从“构建一个包”的思维转向“管理一个可定制的应用组件集合”的思维。初期可能会遇到一些工具链和流程上的挑战但一旦适应其带来的体积优化和灵活交付能力对于提升用户体验和应用质量的价值是巨大的。我的经验是尽早将项目迁移到AAB并在CI/CD流水线中集成bundletool进行自动化测试是平滑过渡的关键。
