告别漫长的HbuilderX云打包排队！uni-app x 安卓本地打包保姆级教程（附白屏、包体积过大排坑指南）

掘金前端

不爱说话郭德纲

2026年2月28日 18:47

接触过 uni-app 的同学，在进行 App 打包时习惯使用 HBuilderX 的“云打包”。但随着项目变大，你一定会遇到这些痛苦：

漫长的排队与等待：打个包动辄半小时起步，遇到高峰期更是无限制延长打包时间

体积过大的“斩杀线” ：包体积稍微大点，HBuilderX 就会提示你需要额外付费才能打包。

恼人的次数限制：每天的免费打包次数有限，稍微改个 bug 想测一下都得精打细算。
各种受限的配置：例如使用谷歌登录时，应用名称会被云打包强制固定为 uniappX，无法修改。

今天，我将手把手教你如何跑通 Android 本地打包流程！一次配置，终身受益！

本地打包的绝对优势：

极速出包：打包时间从原本半小时以上（周五较多人排队打包更是一次一小时以上），直接缩短到 20 秒左右！（视情况而定）
绝对自由：你可以随心所欲地修改 Android 原生配置（如包名、各种第三方登录的名称等）。
自主瘦身：可自行精简 SDK，剔除不需要的模块，完美避开云打包的大体积收费限制。
无限续杯：没有次数限制，没有排队，随心所欲，想打就打！

(注：本文基于 uni-app x 5.01 Alpha 版本演示，其他版本流程基本一致。)

废话少讲，准备动手，准备动手

准备阶段：环境与资源

1. 下载官方离线 SDK

前往 DCloud 官网，下载与你的 HBuilderX 版本完全一致的 Android 离线 SDK。

官方文档链接：doc.dcloud.net.cn/uni-app-x/n…

2. 在 HBuilderX 中生成本地资源

在你的 uni-app x 项目中，点击顶部菜单栏 发行 ➡️ 原生App-本地打包 ➡️ 生成本地打包App资源。
编译完成后，会生成一个以你的 AppID 命名的文件夹（如 __UNI__1940137），复制这个文件夹备用。

勾选你要打包的应用类型：Android or iOS

核心阶段：配置 Android Studio 工程

第一步：打开正确的纯安卓工程

解压刚才下载的官方离线 SDK 压缩包。(如下图所示)

打开 Android Studio，点击 Open（或 File -> Open）。
⚠️重点防坑： 不要直接打开最外层文件夹，一定要展开目录，选中里面的 uniappxnativepackage 这个文件夹，点击打开。（如图所示）

【注意：耐心等待】 打开之后，注意看软件的右下角，会有一个进度条在转，或者显示 Gradle Build Running... / Syncing...。
👉 只要右下角还在转，就什么都不要点，把手离开鼠标，去喝口水。等它彻底转完，左边出现一个带绿色安卓小机器人图标的 app 文件夹，才算准备就绪！

加载成功，准备就绪：

这时候注意你的文件类型识别为了Android，为了方便操作对应文件路径，把Android切换为Project，如图所示：

第二步：导入你的前端代码资源

在 Android Studio 左侧目录树，依次展开：app -> src -> main -> assets -> apps。（如果找不到assets文件夹，可直接在main下自行创建）
将刚才在 HBuilderX 里生成的 __UNI__XXXXXXX 文件夹，直接粘贴到 apps 目录中。（如下图所示）

第三步：修改 App 桌面名称

展开目录：app -> src -> main -> res -> values。
双击打开 strings.xml。
将 uni-app x 中的 uni-app x 修改为你真实的 App 名称。

第四步：修改应用包名 (Package Name)

找到 app 目录直属的 build.gradle（图标带个大象🐘）并打开。
找到 defaultConfig 节点下的 applicationId "com.xxxx.xxxx"。
将其修改为你自己的包名（如 com.yourcompany.app）。
务必点击右上角弹出的 Sync Now 进行代码同步。

注意：修改build.gradle后要点击右上角的 Sync Now应用一下，否则无效

关键阶段：配置证书与离线 AppKey

要让 App 正常运行并成功打包，必须配置签名证书和离线打包 Key，否则打开会直接红屏报错。

第五步：获取云端证书与生成 AppKey

登录 DCloud 开发者后台（dev.dcloud.net.cn），进入你的项目。
在 “Android云端证书” 页面，下载你的 .keystore 证书文件到电脑桌面，并记录下证书密码、证书别名 (Alias) 和 SHA1指纹。
在左侧菜单找到 “各平台信息” -> “离线打包Key管理” 。
填入你刚才配置的包名和 SHA1 指纹，点击生成，复制生成好的那一长串 AppKey。

第六步：将证书放入工程并配置

将下载好的 .keystore 证书文件，直接复制粘贴到 Android Studio 左侧的 app 文件夹根目录下。（如下图所示放到app目录下）

再次打开 app/build.gradle 文件，在 buildTypes { 这一行的正上方，手动添加如下签名配置：

signingConfigs {
        config {
            keyAlias '你的证书别名'
            keyPassword '你的证书密码'
            storeFile file('你的证书文件名.keystore')
            storePassword '你的证书密码'
            v1SigningEnabled true
            v2SigningEnabled true
        }
    }

然后在下方的 buildTypes -> release 里面，加上一行引用：signingConfig signingConfigs.config。
修改完毕后，再次点击右上角的 Sync Now。

第七步：配置离线 AppKey

打开 app -> src -> main -> AndroidManifest.xml。
滑动到文件最下方，在标签的正上方，添加如下代码：

<meta-data
            android:name="dcloud_appkey"
            android:value="在这里粘贴你刚才生成的极长AppKey字符串" />

避坑指南：解决白屏与包体积过大问题（必看！）

如果现在直接打包，你会面临两个新手必踩的坑：打开只有标题栏一片空白，以及包体积高达 150MB+ 。我们需要做最后两步优化。

第八步：解决首页白屏问题

原因： 官方模版默认的 MainActivity.kt 是一个带安卓原生按钮的测试壳子，我们需要把它换成直接启动 uni-app 的代码。
解决：

打开 app -> src -> main -> java -> ... -> MainActivity.kt。
清空里面的所有代码，替换为以下纯净版启动代码（注意包名要保留你自己的）：

package com.example.uniappx_native_package // 这里的 package 保持你文件原有的不要动

import android.os.Bundle
import io.dcloud.uniapp.UniAppActivity

class MainActivity : UniAppActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
    }
}

第九步：App 瘦身（减小包体积）

原因： 离线 SDK 默认是“全家桶”，把微信、支付宝、个推、地图等所有模块全塞进去了。
解决：

打开 app/build.gradle，滑到最底部的 dependencies { ... } 区域。
把你项目中没有用到的功能依赖，在前面加上 // 注释掉。
(例如：没用到华为广告，就注释掉 implementation "com.huawei.hms:ads-lite..."；没用到高德地图，就注释掉 implementation 'com.amap.api:...' 等等)
注释完成后，点击 Sync Now。这能让你的 APK 体积瞬间缩小几十兆！