uniapp 开发Android 之HbuildX 离线打包 app 项目实战

dazhong2012

1249人浏览 · 2025-10-01 09:00:00

dazhong2012 · 2025-10-01 09:00:00 发布

UniApp 结合 HBuilderX 进行离线打包，可以在本地环境更灵活地构建 Android APP。下面我将梳理一份从环境准备到生成 APK 的实战指南，并附上一些常见问题的解决方法。

一、准备工作与环境配置

1. 开始离线打包前，需要准备好以下工具和材料：

准备项	说明	备注
HBuilderX	开发 UniApp 项目的主要 IDE。	从官网下载最新版。
Android Studio	用于编译和构建最终的 APK 文件。	官网下载地址
App 离线 SDK	核心依赖库，提供了 UniApp 运行所需的环境。	官网下载地址关键点：必须确保下载的离线 SDK 版本与你的 HBuilderX 版本一致。可在 HBuilderX 的"帮助"->"历次更新说明"中查看版本号。
Java JDK	建议使用 JDK 1.8 或更高版本（如 JDK 11, 17）。	需在 Android Studio 中配置。本文使用 JDK1.8示例
App AGP	核心依赖库，提供了 Android Gradle Tools 运行所需的环境。	关键点：必须确保与Android Gradle 版本匹配，本文使用 AGP 3.X 作为示例。

2. 离线打包关键步骤

完整的离线打包流程涉及云端配置和本地操作，核心步骤如下图所示：

二、生成本地打包资源

1. 注册DCloud 开发者账号

注册地址： https://dev.dcloud.net.cn/pages/common/login
在这里插入图片描述

2.完成个人手机号验证绑定

在这里插入图片描述

3. 创建应用

在开发者中心–>应用管理–>创建应用，创建完将生成应用 Appid；
在这里插入图片描述

3.uniapp项目配置 Appid

在 HBuilderX 中打开 UniApp 项目，打开manifest.json 文件，基础配置中填写 AppId,并配置 app基本信息;

{
    "name" : "我的app",
    "appid" : "__UNI__xxxxxxx",
    "description" : "",
    "versionName" : "1.0.0",
    "versionCode" : "106",
    //其他配置项
    ......
 },

在这里插入图片描述

4. 生成本地打包资源

在 HBuilderX 中打开 UniApp 项目，点击菜单栏的 “发行” -> “原生App-本地打包” -> “生成本地打包App资源” 。
在这里插入图片描述

成功后，在项目根目录下的 unpackage/resources 目录下会生成一个以项目 AppID 命名的文件夹，这个文件夹就是打包的核心资源。
在这里插入图片描述

三、创建原生App

Android原生工程配置官方文档：
https://nativesupport.dcloud.net.cn/AppDocs/usesdk/android.html

1. 打开Android studio 新建一个空白项目

在这里插入图片描述

2. 选择 Empty Activity 点击 Next。

在这里插入图片描述

3. 生成App目录结构如下：

在这里插入图片描述

项目结构说明

MyProject/
├── build.gradle             # 项目级配置
├── gradle.properties        # 全局属性
├── settings.gradle         # 包含的子模块
├── gradle/
│   └── wrapper/
│       └── gradle-wrapper.properties  # Gradle 版本配置
└── app/
    └── build.gradle         # App 模块配置

4.修改核心配置文件：

1. settings.gradle

rootProject.name = "Emergency"
include ':app'

2.项目级 build.gradle配置

// 项目根目录下的 build.gradle
buildscript {
    repositories {
        google()      // 必须
        jcenter()     // 旧版 Android 项目常用
    }
    dependencies {
        // 使用 AGP 3.6.4（兼容 Gradle 5.6.4）
        classpath 'com.android.tools.build:gradle:3.6.4'
        
        // 如果你的项目使用 Kotlin，还需要添加 Kotlin Gradle 插件
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.3.72"  // 兼容 Kotlin 1.3.x
    }
}

allprojects {
    repositories {
        google()      // 必须
        jcenter()     // 旧版 Android 项目常用
    }
}

task clean(type: Delete) {
    delete rootProject.buildDir
}

3. gradle-wrapper.properties（Gradle 5.6.4）

# gradle/wrapper/gradle-wrapper.properties
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-5.6.4-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

4.app/build.gradle配置

// app/build.gradle
apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'       // 如果使用 Kotlin
apply plugin: 'kotlin-android-extensions'  // 如果使用 Kotlin Android Extensions（已废弃，但旧项目可能还在用）

android {
    compileSdkVersion 29            // 建议至少 28（Android 9.0）
    buildToolsVersion "29.0.3"      // 对应 compileSdkVersion

    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 21             // 最低支持 Android 5.0
        targetSdkVersion 29          // 建议与 compileSdkVersion 一致
        versionCode 1
        versionName "1.0"
        
        // Java 8 兼容性配置
        compileOptions {
            sourceCompatibility JavaVersion.VERSION_1_8
            targetCompatibility JavaVersion.VERSION_1_8
        }
        
        // Kotlin 配置（如果使用 Kotlin）
        kotlinOptions {
            jvmTarget = '1.8'
        }
    }

    buildTypes {
        release {
            minifyEnabled false      // 是否启用混淆
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    
    // AndroidX 基础库（AGP 3.6.x 支持 AndroidX）
    implementation 'androidx.appcompat:appcompat:1.2.0'
    implementation 'androidx.core:core-ktx:1.3.2'  // 如果使用 Kotlin
    implementation 'androidx.constraintlayout:constraintlayout:2.0.4'
    
    // Kotlin 标准库（如果使用 Kotlin）
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.72"
    
    // 测试依赖
    testImplementation 'junit:junit:4.13.2'
    androidTestImplementation 'androidx.test.ext:junit:1.1.3'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.3.0'
}

5.gradle.properties（可选）

# gradle.properties
# 启用 AndroidX（如果项目使用 AndroidX）
android.useAndroidX=true
android.enableJetifier=true  # 自动迁移旧 support 库到 AndroidX

# 配置 Java 8（可选，如果系统默认不是 Java 8）
org.gradle.java.home=C\:\\Program Files\\Java\\jdk1.8.0_391

四. 准备签名证书

方式一：JDK自带工具生成

安卓应用安装需要签名证书。如果你没有，可以使用 JDK 自带的 keytool工具生成：

#生成 key
keytool -genkeypair -v -keystore "F:\key\app_key.jks" -alias myKey -keyalg RSA -keysize 2048 -validity 10000
#查看验证 key
keytool -list -v -keystore "F:\key\app_key.jks" -storetype JKS

请记住设置的别名（alias）、密码(key passwod)以及密钥存储位置、密钥库密码（key store password）信息，后面需要配置在 Android Studio中。

在这里插入图片描述

方式二：Android Studio 中生成

点击菜单栏 Build -> Generate Signed Bundle or APK ,填写密钥存储位置（key store path）、密钥库密码（key store password）、别名（alias）、密码（key password）信息，将自动生成。

在这里插入图片描述

五、下载HbuildX 离线SDK

根据 HbuildX 版本，从官方下载地址下载相同版本的离线SDK 安装包。（本地 HbuildX 版本为4.23）
解压 SDK，SDK目录说明
|-- HBuilder-HelloUniApp App离线打包演示应用
|-- HBuilder-Integrate-AS 集成uni-app的最简示例
|-- SDK SDK库文件目录
|-- Feature-Android.xls Android平台各扩展Feature API对应的详细配置
|-- Readme.txt 版本说明文件及注意事项
|-- UniPlugin-Hello-AS uni原生插件开发示例