---

核心前提（必看）

1. 版本严格对齐：下载的离线 SDK 版本必须与你的 HBuilderX 版本完全一致，否则必白屏 / 闪退。

---

提示：以下是本篇文章正文内容，下面案例可供参考

一、环境准备

• 安装 HBuilderX（最新版）
• 安装 Android Studio（最新版）
• 下载 uni-app x 离线 SDK

准备好你的 uni-app x 项目

二、使用步骤

第一阶段：HBuilderX 生成离线资源

1. 打开你的 uni-app x 项目，点击顶部菜单 发行 -> 原生 App - 本地打包 -> 生成本地打包 App 资源。
2. 等待编译完成，控制台会输出资源路径（如 unpackage/dist/build/app/__UNI__XXXXXX），复制这个文件夹路径备用。
   

第二阶段：Android Studio 工程配置

1. 导入 SDK 工程

• 解压下载的离线 SDK，找到 HBuilder-Integrate-AS 文件夹。
• 打开 Android Studio，点击 File -> Open，选中 HBuilder-Integrate-AS 文件夹打开。
• 关键：等待 Gradle 同步完成（右下角进度条走完），确保工程识别为 Android 项目。
  

2. 替换应用资源

• 在 Android Studio 中切换到 Project 视图，找到路径：simpleDemo/src/main/assets/apps。

• 删除原有 __UNI__XXXXXX 文件夹，将第一阶段生成的你的项目资源文件夹（如 __UNI__123456）完整复制进来。

• 在 Android Studio 中切换到 Project 视图，找到路径：simpleDemo/src/main/java。

• 将第一阶段生成的你的项目资源文件夹"uniappx/app-android/src"下的所有东西完整复制进来。

3. 配置核心参数

(1) 配置 AppID
打开 simpleDemo/src/main/assets/data/dcloud_control.xml，将 内容修改为你的项目 AppID（即资源文件夹名称）。

(2) 配置离线打包 Key（必配）

• 登录 DCloud 开发者后台，进入你的项目 -> 各平台信息 -> 离线打包 Key 管理。
• 填写你的包名（后续会改）和 SHA1 指纹（生成签名文件后获取），生成并复制 AppKey。
• 打开 simpleDemo/src/main/AndroidManifest.xml，找到 <meta-data android:name=“dcloud_appkey”，将 android:value 替换为你的 AppKey。
  

(3) 修改包名、应用名称

• 包名：打开 simpleDemo/build.gradle，修改 defaultConfig 下的 applicationId 为你自定义的包名（如 com.yourcompany.app）。
• 应用名称：打开 simpleDemo/src/main/res/values/strings.xml，修改 app_name 为你的 App 名称。

4. 配置签名证书（正式打包必备）

(1) 生成签名文件
在开发者后台 Android 云端证书 页面下载证书（.keystore 文件），或自己用 keytool 生成。

(2) 放入工程并配置

• 将 .keystore 文件复制到 simpleDemo/ 目录下。
• 打开 simpleDemo/build.gradle，在 android 节点下添加签名配置：

signingConfigs {
    config {
        keyAlias '你的证书别名'
        keyPassword '你的证书密码'
        storeFile file('你的证书文件名.keystore') // 替换为实际文件名
        storePassword '你的证书密码'
        v1SigningEnabled true
        v2SigningEnabled true
    }
}
buildTypes {
    release {
        signingConfig signingConfigs.config // 引用签名配置
        minifyEnabled false // 混淆按需开启
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
    debug {
        signingConfig signingConfigs.config // 调试包也可使用签名
    }
}

• 点击右上角 Sync Now 同步配置。

5. 解决常见问题（必看）

• 16KB 内存页问题：HBuilderX 4.81+ 已自动适配，确保 SDK 版本 >= 4.81，无需额外配置。
• 白屏：检查资源替换是否正确、AppID/Key 是否匹配、包名是否一致。
• 模拟器运行：确保已安装 Android Emulator hypervisor driver

第三阶段：打包构建

1. 在 Android Studio 中点击顶部菜单 Build -> Generate Signed Bundle / APK。
   

2. 选择 APK，点击 Next。

3. 选择签名配置 config，输入密码，点击 Next。
   

4. 选择 Release 版本，点击 Finish，等待打包完成。

5. 打包产物在 simpleDemo/release/ 目录下，即为可安装的 APK。
   

---

官方参考

• uni-app x Android 离线打包官方文档

• uni-app x iOS 离线打包官方文档

总结

以上就是今天要讲的内容，本文详细介绍了2026年新版uni-app x离线打包保姆级教程方法。