保姆级 uni-app Android 本地离线打包全教程，从环境配置到 APK 生成一站式搞定

前言

很多 uni-app 开发者在项目开发完成后，都会面临应用打包的需求。官方提供的云打包虽然操作简单，但存在打包次数限制、无法深度自定义原生配置、隐私合规整改需修改原生代码等诸多限制，这种情况下，Android 本地离线打包就成了更灵活的最优解。

本文将从 0 到 1 带大家完整走通 uni-app 项目的 Android 本地打包全流程，涵盖环境准备、证书申请、资源配置、打包编译、高频踩坑解决全环节，哪怕是没有 Android 开发经验的前端开发者，也能跟着步骤一步步完成打包。

一、前置环境准备

在开始打包前，请确保你已经准备好以下环境，避免后续操作出现环境兼容问题：

HBuilderX 正式版：建议使用最新稳定版，必须和后续下载的离线 SDK 版本完全一致
Android Studio 最新稳定版：用于原生项目的配置与打包编译
JDK 11 及以上版本：Android Studio 一般会自带对应版本，无需额外手动安装
有效的 DCloud 开发者账号：用于申请 AppID、签名证书、dcloud_key 等核心配置

二、申请应用标识与签名证书

2.1 获取 DCloud AppID

AppID 是 uni-app 应用的唯一标识，是所有配置的核心，获取步骤如下：

登录DCloud 开发者中心
进入「我的应用」页面，点击「创建应用」，填写应用名称、选择应用类型，完成创建
创建完成后，在应用详情页即可获取到你的 AppID（格式为__UNI__XXXXXXX），请妥善保存该 ID

2.2 生成并下载 Android 签名证书

签名证书是 Android 应用的唯一身份凭证，上架应用市场必须使用正式签名证书，这里我们直接通过 DCloud 平台生成，无需手动执行 keytool 命令：

在应用详情页，点击「证书管理」→「创建证书」
填写证书相关信息（别名、密码、姓名、组织等），务必记住证书别名和密码，后续打包必须使用
点击创建，等待 1 分钟左右刷新页面，证书生成完成后点击「下载证书」，将后缀为.keystore的证书文件保存到本地
点击「查看证书」，复制证书的 MD5、SHA1、SHA256 值，后续申请 dcloud_key 会用到

2.3 申请 dcloud_key

dcloud_key 是 uni-app 离线打包的必备配置，用于校验应用的合法性，申请步骤如下：

在 DCloud 开发者中心的应用详情页，点击「各平台信息」→「新增」
平台选择「Android」，填写刚才生成证书的 SHA1 值、应用包名（包名格式一般为com.xxx.xxx，全小写无特殊字符，后续所有配置的包名必须和此处完全一致）
点击保存，即可生成 Android 平台的 dcloud_key，复制该值妥善保存

三、打包前置资源准备

3.1 生成 uni-app 本地打包资源

打开 HBuilderX，进入你的 uni-app 项目，打开manifest.json文件，确认「基础配置」中的 AppID 已经填写为刚才申请的 DCloud AppID
在项目根目录右键，选择「发行」→「原生 App - 本地打包」→「生成本地打包 App 资源」
等待编译完成，HBuilderX 控制台会输出资源生成的路径，打开路径会看到一个以 AppID 命名的文件夹，这就是我们需要的本地打包资源

【划重点】必须确保 HBuilderX 的版本和后续下载的离线 SDK 版本完全一致，否则会出现应用闪退、资源加载失败等问题！

3.2 下载 uni-app Android 离线 SDK

访问uni-app 官方离线 SDK 下载页
下载和你的 HBuilderX 版本完全匹配的 Android 平台 SDK
下载完成后解压压缩包，解压后的文件夹中，我们核心使用HBuilder-Integrate-AS这个官方集成示例项目，后续所有配置都基于该项目修改

四、Android Studio 端全流程配置

4.1 导入示例项目

打开 Android Studio，点击「Open」，选择刚才解压出来的HBuilder-Integrate-AS文件夹，点击确定导入项目
首次导入项目会自动同步 gradle 依赖，若出现下载慢、同步失败的问题，可修改项目根目录的build.gradle文件，添加阿里云国内镜像源，配置如下：

buildscript {
repositories {
maven { url 'https://maven.aliyun.com/repository/google' }
maven { url 'https://maven.aliyun.com/repository/public' }
maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
google()
mavenCentral()
}
dependencies {
classpath "com.android.tools.build:gradle:7.0.0"
}
}

allprojects {
repositories {
maven { url 'https://maven.aliyun.com/repository/google' }
maven { url 'https://maven.aliyun.com/repository/public' }
google()
mavenCentral()
// uni-app 官方仓库
maven { url "https://maven.dcloud.net.cn" }
}
}

4.2 替换本地打包资源

在 Android Studio 的项目视图中，进入app→src→main→assets→apps文件夹
将 apps 文件夹内原有的示例文件全部删除，把 HBuilderX 生成的、以 AppID 命名的文件夹完整复制到 apps 文件夹下

4.3 校验 AppID 一致性（核心！90% 的闪退问题都出在这里）

必须确保以下三处的 AppID 完全一致，否则会出现应用启动闪退、资源加载失败的问题：

复制到 apps 文件夹下的资源文件夹名称
HBuilderX 项目中manifest.json文件里配置的 AppID
项目中app→src→main→assets→data→dcloud_control.xml文件里的 appid 配置

打开dcloud_control.xml文件，修改配置如下：

复制代码

<hbuilder>
<apps>
    <app appid="__UNI__XXXXXXX" appver=""/>
</apps>
</hbuilder>

4.4 配置应用包名

打开项目app目录下的build.gradle文件
修改defaultConfig中的applicationId为你申请 dcloud_key 时填写的包名，示例如下：

defaultConfig {
applicationId "com.yourname.appname" // 替换为你的包名
minSdkVersion 21
targetSdkVersion 33 // 谷歌应用市场要求33及以上，国内市场一般30以上即可
versionCode 1
versionName "1.0.0"
}

【注意】此处的包名必须和申请 dcloud_key 时的包名完全一致，否则会导致 dcloud_key 校验失败，应用无法正常启动

4.5 配置 dcloud_key

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

4.6 配置签名证书

将之前下载的.keystore签名证书文件，复制到项目的app目录下
打开 app 目录下的build.gradle文件，在 android 节点下添加签名配置，示例如下：

android {
signingConfigs {
config{
// 替换为你的证书文件名
storeFile file('your-cert.keystore')
// 替换为你的证书密码
storePassword '你的证书密码'
// 替换为你的证书别名
keyAlias '你的证书别名'
// 替换为你的证书别名密码
keyPassword '你的证书密码'
}
}

}

五、执行打包，生成正式 APK

所有配置完成后，点击 Android Studio 顶部的「Sync Project with Gradle Files」按钮，同步配置，确保无报错
点击顶部菜单栏的「Build」→「Generate Signed App Bundle or APK」
在弹出的窗口中，选择「APK」，点击 Next
选择我们配置的 release 签名，填写证书密码、别名等信息，点击 Next
等待打包完成，Android Studio 右下角会提示打包成功，点击「locate」即可打开生成的 APK 文件所在文件夹，该 APK 就是可安装到安卓手机的正式安装包

六、高频踩坑问题与解决方案

表格

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

七、总结与拓展

本文完整讲解了 uni-app Android 本地离线打包的全流程，从环境准备、证书申请、资源配置到打包生成 APK，覆盖了新手会遇到的大部分核心问题。

本地打包不仅可以摆脱云打包的次数限制，还支持自定义原生代码、修改权限配置、集成第三方原生 SDK，满足更多个性化需求。后续如果需要上架应用市场，还可以对生成的 APK 进行加固、对齐、重签名等操作，提升应用的安全性。

如果在操作过程中遇到任何问题，欢迎在评论区留言交流～