Hbuilder+Uni-app 离线打包APK

前置环境准备

开始打包前，请确保以下环境已就绪，以避免后续操作中出现环境兼容性问题：

HBuilderX 正式版：建议使用最新稳定版，必须与后续下载的离线 SDK 版本完全匹配。二者的版本号若不一致，应用启动时可能弹出版本不匹配的提示。

Android Studio 最新稳定版：用于原生项目的配置与打包编译。

App离线SDK下载：https://nativesupport.dcloud.net.cn/AppDocs/download/android.html

有效的 DCloud 开发者账号：用于申请 AppID、签名证书、dcloud_key 等核心配置。

开始

1、生成本地打包 App 资源

在项目根目录右键，选择「发行」→「原生 App - 本地打包」→「生成本地打包 App 资源」；

等待编译完成，HBuilderX 控制台会输出资源生成路径。打开该路径，会看到一个以 AppID 命名的文件夹，这就是需要的本地打包资源。

2、下载SDK，解压

3、使用 Android Studio 打包

3.1打开 Android Studio，点击「Open」，选择刚才解压出的 HBuilder-Integrate-AS 文件夹，点击确定导入项目。

3.2 修改项目名称（AndroidManifest.xml）

先点开label后再ctrl+左键进入strings.xml 修改为你的APP名称

3.3创建安卓云端证书（https://dev.dcloud.net.cn/）

3.4配置 dcloud_key（AndroidManifest.xml）

打开项目 simpleDemo → src → main 目录下的 AndroidManifest.xml 文件，找到 meta-data 标签中 name 为 dcloud_appkey 的配置，将 value 替换为申请的 dcloud_key：

3.5修改appid（dcloud_control.xml）

3.6修改applicationId（build.gradle）

修改为离线打包KEY里面的“包名/appid/域名”

3.7修改signingConfigs（build.gradle）

keyAlias是APPID，keyPassword、storePassword是云端证书的密码。storeFile file是证书文件名称，证书文件记得下载到Demo根目录

3.8替换Hbuilder生成的APP资源（simpleDemo\src\main\assets\apps）

3.9修改Build Variants

3.10 更换图片、启动动画（替换即可）

manifest.json 中的图标配置在离线打包时不会生效，必须替换 Android Studio 原生工程中的图片资源。

3.11 打包APK

点击顶部菜单栏的「Build」→「Generate App Bundle or APK」；

常见问题与解决方案

问题现象	核心解决方案
应用安装后启动直接闪退	1. 校验三处 AppID 是否完全一致； 2. 确认 HBuilderX 版本与离线 SDK 版本完全匹配； 3. 检查 dcloud_key 是否与包名、证书匹配； 4. 查看 Logcat 日志定位具体报错。
gradle 同步失败、依赖下载慢	1. 替换为阿里云国内镜像源； 2. 检查 gradle 版本与 Android Studio 版本是否兼容。
打包报错：Google Play 要求 target API level 33 或更高	将 `build.gradle` 中的 `targetSdkVersion`、`compileSdkVersion` 修改为 33 或更高版本。Google Play 已要求 target API level 不低于 35。
应用启动白屏、资源加载失败	1. 检查本地打包资源是否完整复制到 `apps` 文件夹； 2. 确认 AppID 配置正确； 3. 重新生成本地打包资源并替换。
dcloud_key 校验失败	1. 检查包名是否与申请 key 时的包名完全一致； 2. 确认证书 SHA1 值与申请 key 时填写的一致； 3. 检查 dcloud_key 是否复制错误或含有多余空格