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

接触过 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 { 这一行的正上方，手动添加如下签名配置：

java 复制代码

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。
滑动到文件最下方，在标签的正上方，添加如下代码：

ini 复制代码

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

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

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

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

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

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

kotlin 复制代码

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 体积瞬间缩小几十兆！