适合人群：已经会用 HBuilderX 开发 uni-app，但第一次尝试离线打包 Android 的同学。
前言：为什么要用离线打包？
用 HBuilderX 云打包很方便，但有几个痛点：•每次打包都要排队等云端编译•无法自由定制原生层（比如集成第三方 SDK、修改原生代码）•免费版有次数限制，企业版要付费
离线打包就是把”云端编译”搬到你自己电脑上，用 Android Studio 完成最后的打包动作。听起来复杂，其实就三步：准备资源 → 塞进工程 → 编译出包。
一、准备工作（别跳过，版本不对后面全白费）
1. 工具清单
| 工具 | 版本要求 | 下载地址 |
|---|---|---|
| HBuilderX | 你项目用的版本（如 5.24） | https://www.dcloud.io/hbuilderx.html |
| Android Studio | 最新稳定版，内置 JDK 11/17 | https://developer.android.com/studio |
| uni-app 离线 SDK | 必须和 HBuilderX 同版本号 | https://nativesupport.dcloud.net.cn/AppDocs/download/android.html |
2. 环境检查
- 电脑用户名和项目路径不要有中文和空格（比如别放
C:\用户\张三\桌面\，放D:\Android\这种） - Android Studio 打开后，确认 SDK Manager 里装了：
compileSdk 33+targetSdk 33+（低于 33 会在运行报ExpiredTargetSdkVersion错误）
⚠️ 最重要的一个原则：离线 SDK 版本号必须和 HBuilderX 版本号一致。
比如你用 HBuilderX 5.24 开发，就下载 5.24 的离线 SDK。不一致 = 白屏/闪退/各种诡异问题。
二、在 DCloud 开发者中心申请 AppKey
这一步是”身份认证”，告诉 DCloud 服务器：这个 App 是你开发的，有权使用离线打包。
1. 登录并创建应用
打开 https://dev.dcloud.net.cn ，用你的 DCloud 账号登录。
- 进入「应用管理」→ 找到你的 uni-app 项目
- 记下 AppID（格式类似
__UNI_XXXXXX），后面会反复用到
2. 创建/上传 Android 证书
离线打包必须用自己的签名证书。如果你已经有 jks 文件，直接上传；没有的话在这里创建：
- 证书管理 → 创建 Android 证书
- 填写信息后，记下：
- 包名（如
com.mycompany.myapp，全小写，后面不能改） - 证书 SHA1 / SHA256（页面上会显示）
- 别名 和 密钥库密码
3. 生成离线 AppKey
- 各平台信息 → 新增 Android 平台
- 填入包名 + SHA1 + SHA256
- 提交后会生成一串很长的 离线 AppKey，复制保存好
三、从 HBuilderX 导出前端资源
回到 HBuilderX，打开你的 uni-app 项目：
菜单栏 → 发行 → 原生App-本地打包 → 生成本地打包App资源等待编译完成后，资源会生成在：
你的项目/unpackage/resources/__UNI_XXXXXX/这个文件夹里就是 www/ 等前端编译产物。把它整个复制出来备用。
四、用 Android Studio 打开离线工程
1. 解压离线 SDK
下载的离线 SDK 解压后，你会看到几个文件夹。我们要用的是 HBuilder-Integrate-AS 这个示例工程。
2. 导入工程
- 打开 Android Studio →
File → Open - 选择
HBuilder-Integrate-AS文件夹 - 等待 Gradle 同步完成（第一次可能比较慢，耐心等）
如果同步卡住不动，可以：•断开重连网络重试•或手动配置 Gradle 离线包（新手建议先等它自己跑完）
3. 替换前端资源
找到这个路径：
simpleDemo/src/main/assets/apps/
•删掉里面原有的 __UNI_XXX 文件夹•把第三步生成的 整个 __UNI_XXXXXX 文件夹 复制进来
然后打开 assets/data/dcloud_control.xml，确认里面的 appid 和你的一致：
<app appid="__UNI_XXXXXX" />五、修改工程配置（照着改就行）
1. 改包名（build.gradle）
打开 app/build.gradle，找到 defaultConfig 节点：
android {
defaultConfig {
applicationId "com.mycompany.myapp" // ← 改成你申请的包名
minSdk 21
targetSdk 34
versionCode 1
versionName "1.0.0"
ndk {
abiFilters 'armeabi-v7a', 'arm64-v8a'
}
}
}2. 填入 AppKey（AndroidManifest.xml）
打开 app/src/main/AndroidManifest.xml，在 <application> 节点内添加：
<meta-data
android:name="dcloud_appkey"
android:value="你申请的离线AppKey" />同时确保 PandoraEntry 和 PandoraEntryActivity 的配置存在（示例工程里已经有了，别删）。
3. 配置签名（app/build.gradle）
如果你已经有 jks 证书文件，把它放到 app/ 目录下，然后在 build.gradle 里添加：
android {
signingConfigs {
release {
storeFile file('release.jks') // jks 文件名
storePassword '你的密码'
keyAlias '你的别名'
keyPassword '你的密码'
}
}
buildTypes {
release {
signingConfig signingConfigs.release
minifyEnabled false
}
}
}如果暂时只想跑起来看看效果，可以用 Debug 包，跳过这步。但正式发布必须有签名。
六、编译出 APK
方式一：先打个 Debug 包试试水
Android Studio 菜单 → Build → Build APK(s)编译完成后，右下角会弹出提示，点击 locate 就能找到 APK 文件：
app/build/outputs/apk/debug/app-debug.apk把这个文件传到手机上安装，如果能正常打开你的应用首页，说明链路通了！
方式二：正式 Release 包
Android Studio 菜单 → Build → Generate Signed Bundle / APK→ 选 APK → 选你的 jks 文件 → 选 release → Finish产出路径：
app/build/outputs/apk/release/app-release.apk这个就是可以上架应用商店的正式包。
七、常见问题速查表
| 问题 | 原因 | 解决办法 |
|---|---|---|
| 启动闪退 | AppID 不一致 | 检查 manifest.json、文件夹名、dcloud_control.xml 三处是否一样 |
| 白屏 | SDK 版本和 HBuilderX 不一致 | 重新下载对应版本的离线 SDK |
| 提示 AppKey 校验失败 | 包名/签名/AppKey 不匹配 | 确认三者对应，改了任一项要重新申请 AppKey |
| 安装失败提示证书不一致 | 手机上有同包名的旧版 | 卸载旧版再装 |
| 改了前端代码但 App 没变 | 没重新生成资源 | 每次改代码都要重新「生成本地打包资源」并覆盖 assets/apps |
| Gradle 同步报错 | 网络/镜像问题 | 换网络或配置阿里云 maven 镜像 |
八、总结：一次成功的检查清单
打包前对照一下，全打勾就能过：
- HBuilderX 版本 = 离线 SDK 版本
- AppID 在三处一致（manifest / 文件夹名 / dcloud_control.xml）
- AndroidManifest 里填了正确的 dcloud_appkey
- applicationId 和申请 AppKey 时的包名一致
- 签名配置正确（正式包必须）
- 资源文件夹完整放进了 assets/apps/
最后更新：2026 年 9 月，基于 HBuilderX 4.x + uni-app 离线 SDK 验证通过。