1. 先搞清楚APK和AAB不是简单的后缀名差别1.1 两种格式在安装链路上的本质差异很多开发者在第一次接触打包时会把APK和AAB当成两个不同版本的文件仿佛只是后缀名不同。实际上这两种格式的定位差了十万八千里。APKAndroid Application Package是Android系统真正能识别并安装的文件格式它包含了完整代码、资源文件和签名信息。用户拿到APK点击安装系统直接解析、校验签名、写入应用。整个过程不依赖任何中间环节。AABAndroid App Bundle则是为Google Play量身定做的发布格式。它不是一个安装包而是一个包含了所有可能的代码、资源和配置的素材母版。Google Play拿到AAB后会针对不同用户设备的屏幕密度、CPU架构、语言环境动态生成一套只包含必要资源的APK集合在Play商店内部叫App Bundle拆分包而在本地工具链里则是apks文件。所以AAB本身不能直接装进手机。你可以把APK理解成做好的外卖一份装好直接吃AAB则是中央厨房的预制菜料包平台根据每个客人的口味临时配菜出餐。前者是一次性交付后者是分发型交付这就是两者最本质的区别。1.2 什么时候必须用AAB什么时候老老实实打APK先说结论目标市场是Google Play且应用包体超过或者你需要享受动态交付优化必须用AAB。目标市场是国内应用商店或者需要直接分发安装包、做企业内测、给第三方渠道包一律用APK。国内主流商店对AAB的支持一直很保守。虽然华为AppGallery Connect、腾讯应用宝等平台已经开始接受AAB格式但绝大多数中小渠道、SDK接入厂商、硬件厂商预装依然只认APK。而且国内商店普遍要求你提供签名证书信息或加固后的APK绕不开发行包这个环节。还有一个很现实的问题Google Play在2021年8月之后强制要求新应用必须使用AAB上架。而国内商店审核则要你提交兼容性测试报告、隐私政策截图甚至指定CPU架构。这套流程决定了你不可能只用AAB打天下。我的建议是本地开发、内测、国内上架全部走APK只有上传Google Play时单独构建一次AAB。这样避免同一个工程维护两套打包逻辑也不至于到上架关头发现签名不匹配。1.3 从AAB到APKbundletool怎么把新格式转回旧格式有些开发者手里只有AAB但临时需要APK安装包这时候就要借助Google官方提供的bundletool工具。bundletool是一个Java命令行工具负责把AAB构建成不同形态的apks文件也能直接把apks安装到设备。基本用法如下下载bundletoolGitHub上的google/bundletool仓库里拿最新的jar包。生成APKS集合java -jar bundletool.jar build-apks \ --bundleyour_app.aab \ --outputyour_app.apks \ --ksyour_keystore.jks \ --ks-passpass:your_password \ --ks-key-aliasyour_alias \ --key-passpass:your_key_password注意这里必须带上签名文件因为AAB打包成apks的过程实质上是一次重新签名。安装到设备java -jar bundletool.jar install-apks --apksyour_app.apks如果你只想提取通用APKuniversal.apk用来分发java -jar bundletool.jar build-apks --bundleyour_app.aab --outputyour_app.apks --modeuniversal然后解压apks文件里面就有一个universal.apk这个包体积通常很大但包含所有资源可以直接安装。提示用此方式提取出的universal.apk虽然能装但只建议用于内测或临时使用正式渠道仍然应该从AAB渠道按设备分发否则就失去了AAB缩减体积的意义。2. Android Studio原生打包从新建签名到Gradle面板2.1 生成keystore签名文件时最容易忽视的细节原生Android打包的第一步是准备签名也就是keystore文件。很多新手直接跳过这一步Build之后想装真机时发现连调试包都装不上原因就是他们还没理解签名在Android体系里的地位。签名相当于应用的身份证。系统通过签名校验两个东西应用是否被篡改以及两个包名相同的应用是否属于同一个开发者。如果你用A签名发了v1.0后面换B签名发v1.1用户无法通过覆盖安装升级只能卸载重装数据全部丢失。生成正式keystore有两个主要方式Android Studio的Build菜单里跟着向导走或者用命令行keytool操作。我习惯用命令行因为可控性强每个字段都知道填了什么。keytool -genkeypair -v \ -keystore release.keystore \ -alias your_alias \ -keyalg RSA \ -keysize 2048 \ -validity 10000命令会提示你输入密码、姓名组织、城市等信息。有几个容易踩的细节证书有效期建议写10000天以上不要默认90天否则上架后证书过期得重新做签名迁移麻烦到怀疑人生。别名alias和密码务必记好。密码忘了等于签名废了应用再也无法升级。把keystore文件纳入版本管理之外的独立备份空间换电脑时第一个要恢复的就是它。2.2 build.gradle里值得逐行确认的关键配置原生打包绕不开Gradle。很多人报错都是因为build.gradle里某些字段配置过头或漏配。以AGPAndroid Gradle Plugin8.x版本为例重点看这几个节点android { namespace com.yourcompany.yourapp compileSdk 34 defaultConfig { applicationId com.yourcompany.yourapp minSdk 24 targetSdk 34 versionCode 1 versionName 1.0.0 } signingConfigs { release { storeFile file(../keystore/release.keystore) storePassword your_password keyAlias your_alias keyPassword your_key_password } } buildTypes { release { minifyEnabled true shrinkResources true proguardFiles getDefaultProguardFile(proguard-android-optimize.txt), proguard-rules.pro signingConfig signingConfigs.release } } }几个容易被忽略的点namespace和applicationId在AGP 8.0之后必须分开理解。namespace是代码里的R类包名applicationId是安装到系统中的应用ID。如果你从老项目升级过来namespace没填会直接编译失败。versionCode是递增的整数每次发版必须比上一次大。它不会展示给用户但应用市场靠它区分新旧版本。versionName才是用户看到的1.0.0。minifyEnabled打开混淆后如果项目里用了反射或第三方SDK需要在proguard-rules.pro里补充keep规则否则打包出的App运行起来随时闪退。2.3 用Generate Signed App Bundle/APK跑通正式包准备工作做完打包流程本身反而是最简单的在Android Studio菜单栏选择Build-Generate Signed App Bundle / APK。选择生成APK还是AAB下一步填入keystore路径和密码。选择release构建类型勾选签名Finish。等待Gradle任务跑完APK会生成在app/build/outputs/apk/release/目录。顺便说一句如果你只改了代码想快速出包可以在Build Variants面板把构建类型切到release然后直接Build APK但此时用的是debug签名只适合内部测试。2.4 版本号与多环境切换的工程经验项目变大之后版本管理就变得很关键。我见过不少项目把API环境地址硬编码在代码里打测试包改一次代码、打生产包再改一次代码来回折腾。更好的做法是在build.gradle里用buildConfigField区分环境buildTypes { debug { buildConfigField String, API_BASE_URL, \https://test.example.com/\ } release { buildConfigField String, API_BASE_URL, \https://api.example.com/\ } }代码里直接用BuildConfig.API_BASE_URL取值。这样打包时完全不用动代码选择不同的Build Variant就能得到对应环境的包签名也可以统一用release签名内测包和正式包保持一致减少内测没问题、上线有问题的争议。3. uni-app三条打包路线云打包、离线打包、本地方案3.1 云打包HBuilderX里五分钟跑通但要知道资源限制uni-app最吸引人的地方就是一套代码可以出多端而打包App最省事的方案就是用HBuilderX自带的云打包服务。具体操作在HBuilderX中打开项目确认manifest.json里的基础配置已经填好应用名称和版本号。点击菜单栏发行-原生App-云打包。选择Android平台勾选使用云端证书或者上传你自己的keystore证书。输出格式选择APK或AAB。点击打包等待云端构建完成下载安装包。云打包默认会给未上传证书的应用生成一个DCloud公共证书这种包适合快速验证但不能用于上架因为证书不在你手里后续无法升级覆盖。云打包有一个比较容易被忽略的问题虽然操作简单但打包时选择的模块一定要和项目里实际用到的插件对应上。比如你集成了NFC插件manifest里没勾选NFC模块打包出的App运行到NFC相关页面时直接闪退没有任何提示。注意云打包受DCloud云端资源调度影响高峰期可能要排队。如果发布到应用商店的时间点比较紧张建议至少提前半天发起打包。3.2 manifest.json里的配置决定你打包能不能过uni-app的manifest.json是App端的核心配置文件它不像原生Android的AndroidManifest.xml那么直接但映射了很多原生配置。重点关注这几块基础配置应用名称、AppIDDCloud分配的、版本号、版本名。版本名会和Android原生versionName对应商店审核时会显示。图标配置uni-app支持自动生成各种尺寸的图标但源图必须清晰建议提供1024x1024的原图不要用带圆角的透明背景图否则有些商店审核会提示图标存在黑边。模块配置这里控制App端打包时会集成哪些原生模块。定位、地图、支付、推送、NFC、蓝牙都是独立模块按需勾选。多勾没问题最多包体变大少勾的话运行时找不到类。SDK配置比如高德地图需要申请Key并填入微信登录需要填入AppID和AppSecret。这些配置在云打包时会写入原生工程配置错误通常不会导致打包失败但功能在运行时不可用。权限配置uni-app提供可视化权限勾选。如果漏了存储权限Android 13以上设备访问相册会直接失败。3.3 离线打包把uni-app代码塞进Android Studio工程云打包虽然方便但受限于云端环境很多团队在需要深度集成原生代码、或者想接入自有推送通道时都会转向离线打包。离线打包的原理是DCloud官方提供了一个Android离线SDK包里面已经封装好了uni-app的渲染引擎和基础能力。你需要做的是把这个SDK作为依赖放进Android Studio工程然后把HBuilderX导出的前端资源放进指定目录。基本流程从DCloud官网下载与当前HBuilderX版本对应的Android离线SDK。用Android Studio创建或打开一个空工程将SDK中的library模块导入。在build.gradle中配置签名、包名、版本号。在HBuilderX中点击发行-原生App-本地打包-生成本地打包App资源得到www目录。将www目录复制到Android工程的assets/apps/你的appid/www中。在AndroidManifest.xml中确认AppID、启动页、图标指向正确然后按原生Android方式打包。离线打包最大的坑是版本匹配。HBuilderX升级后离线SDK如果没跟着升跑起来经常出现白屏或者页面渲染异常。核心原因是前端编译产物和原生引擎版本不匹配所以升级HBuilderX后一定要同时替换离线SDK。另一个坑是第三方模块。离线打包时uni-app的内置模块还需要在dcloud_uniplugins.json文件中手动注册。云打包是自动完成的离线打包漏了这一步原生插件会静默失效。3.4 一条容易忽略的稳定路径先云打包验证再离线打包交付我在实际项目里经常采用混合验证策略先用云打包快速出包跑通业务逻辑确认功能没问题后再用离线打包做正式交付包。云打包本质上是DCloud的服务器在帮你编原生工程它的日志和报错信息有限出了问题不太好排查而离线打包在本地Android Studio里Gradle输出完整崩溃日志可追踪问题定位会顺畅很多。如果你决定走离线打包建议团队里至少有一个熟悉原生Android构建的人否则遇到Gradle依赖冲突、signingConfig配置错误这类问题会非常吃力。4. 签名不匹配的坑debug签名、证书过期与包名纠纷4.1 debug签名为什么能装、升级却失败搞懂签名原理的人通常会遇到一个经典场景测试阶段用Android Studio直接Run装上的App后来换成了签名APK安装时提示应用未安装或签名不一致。原因很简单Android Studio的Run任务默认用的是debug.keystore签名和release正式签名不是同一个证书。系统只认包名和签名的组合包名相同但签名不同就认为这是两个完全不同的应用不允许覆盖安装。这个问题的解决方案有两个统一使用release签名在buildTypes.debug里也指定signingConfig signingConfigs.release。测试阶段卸载重装。卸载会清数据适合开发早期但做SDK升级测试、数据迁移验证时必须保证签名一致。我建议从一开始就统一签名。第一次接入推送、登录这类SDK时指纹信息到处要用debug和release两套签名会同时出现在第三方平台配置里自己都会搞混。4.2 换电脑重签名的连锁反应很多自由开发者会在家里电脑和公司电脑之间切换如果keystore文件没有放在云盘或Git仓库里换电脑后重新生成一个新keystore就会触发连锁反应老用户无法覆盖安装新版本。微信登录、支付宝支付等平台的签名指纹失效支付回调异常。应用市场重新上架时需要重新验证证书归属。所以keystore文件必须异地备份而且建议备份两到三份。我通常把它放在公司Git私服的独立仓库中仓库设为私密同时U盘物理备份一份并新建一个文本记录密码和别名绝对不只在本地电脑放一份。4.3 多渠道打包时的动态签名配置如果同一套代码要出多个渠道包每个渠道可能需要不同的证书或不同的applicationId。Gradle的productFlavors可以解决这个问题productFlavors { official { applicationId com.company.app signingConfig signingConfigs.release } partner { applicationId com.company.app.partner signingConfig signingConfigs.partner } }这样在Build Variants里能直接切换渠道一次构建出多个包。不过要提醒一句多渠道配置越复杂打包出错的概率越高。如果是小团队使用同一证书打多渠道包靠渠道号字段区分就能满足绝大多数需求不必为了多渠道独立签名增加维护成本。5. 打包报错的典型排查链路与落地修复5.1 图标/启动图导致的构建失败如果你在Android Studio离线打包或云打包时遇到资源相关报错先检查图标和启动图。这类问题的特征是报错信息里出现res、mipmap、icon或者launch image关键字。常见原因使用了带Alpha通道的JPG系统不认。图片尺寸不是规范的512, 1024, 192等规格。文件名带有中文或异常字符。解决办法很朴素用PNG格式去掉透明通道按官方建议的尺寸重新导出并确保文件名只包含小写字母、数字和下划线。5.2 第三方模块缺失导致的运行时崩溃这一类问题最阴险——打包时不报错功能跑起来才崩。典型的错误日志是ClassNotFoundException或UnsatisfiedLinkError。我之前遇到过一个NFC读取项目云打包时没有勾选NFC模块代码调用到NFC能力时直接闪退。后来打开manifest.json勾选模块重新打包问题消失。每次新增第三方插件或调用系统硬件能力之前先去manifest.json的模块配置里确认是否已经勾选。这是一个成本最低但回报最高的习惯。5.3 打包速度慢与Gradle依赖拉不下来的处理方法Android Studio创建的工程默认从Google的Maven仓库拉依赖国内网络环境下经常卡在Downloading状态半天没动静。处理思路分两步修改settings.gradle里的仓库地址增加阿里云镜像pluginManagement { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } google() mavenCentral() } }Gradle发行包下载慢的话手动下载对应版本的gradle-x.x-all.zip放到本机~/.gradle/wrapper/dists/目录下对应的文件夹中重试构建即可。不用盯着进度条干着急。5.4 打包成功后安装不了的几种现场打包成功只是第一步安装失败才是让人头大的问题。常见现场有解析包错误通常是下载过程文件损坏或者APK没有完整传输重新拷贝文件再试。应用未安装可能是包名冲突手机里已经装了同名不同签名的包。安装失败设备提示版本过低minSdk高于手机系统版本。检查minSdk配置比如minSdk 26就装不到Android 8.0以下的设备。空间不足包体太大或者手机存储耗尽和代码无关清理即可。处理这类问题时先区分是包的问题还是设备的问题。把APK换一台设备安装如果同样报错再回看构建配置如果第二台设备能装就重点排查当前设备上的旧包和系统版本。6. 上架应用市场前的最后检查与发布建议6.1 国内主流商店的包体要求各应用商店表面上大同小异实际要求差别不小。整理一份我踩过坑之后的对照表商店包格式签名要求其他常见注意点华为AAB或APK需上传证书指纹需要申请AGC应用填写隐私政策小米APK支持多家证书需要测试账号隐私政策需主动填写应用宝APK需要签名需要软著或授权书包体无特殊限制OPPOAPK自研加固需要隐私说明敏感权限要写清楚用途vivoAPK自研加固需要兼容性测试部分类目要ICP备案还有一个大环境因素2023年后国内App上架基本都要求完成ICP备案否则部分商店不给上架。所以接到上架需求时先把备案这块及时提上日程。6.2 一个实用的发布前自查清单以下清单是我每次上架前固定过一遍的你可以直接抄版本号versionCode比商店里已有的最高版本大。签名文件是正式的release签名不是DCloud公共证书或debug签名。不同商店的包包名没有交叉冲突。隐私政策链接能正常访问且内容里记录了收集的权限。应用需要的敏感权限都有明确的使用场景说明。在Android 13或更高版本设备上跑过一轮主流程。用同一签名覆盖安装旧版本验证数据升级链路正常。6.3 后续升级与多环境维护的经验应用上线不是终点后续的每一次发版都是在打包。维护阶段我的经验是保留每个已发布版本对应的打包分支或Tag确保随时能回滚出旧版本包。每次发布前在本地归档一份APK不要只依赖应用市场后台。如果项目同时维护多个App比如商户版、用户版把签名、包名、环境配置做成一张表固定团队内公开避免人员交接时信息断层。还有一个小建议APK发布到市场后内测分发可以借助第三方分发平台但一定要把内测包和正式包通过版本号、包名严格区分开否则用户装了内测版之后永远收不到正式版升级通知。我个人的体会是打包这件事看起来简单但真正让项目稳定的从来不是某一次打包成功而是一整套围绕签名、版本、渠道、证书的管理习惯。把这些基础工作做扎实不管是用Android Studio原生打包还是uni-app云打包离线打包都不会在关键时刻掉链子。