本地一键生成 Android 自定义基座（Debug）和 正式发布包（Release），不用排队等云打包。
| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 13 天前 | ||
| 22 天前 | ||
| 13 天前 | ||
| 14 天前 | ||
| 13 天前 | ||
| 17 天前 | ||
| 13 天前 |
Android本地打包工具
本地一键生成 Android 自定义基座（Debug） 和 正式发布包（Release），不用排队等云打包。
选项目 → 点打包，剩下的交给插件：模块自动识别、依赖自动注入、权限自动同步、UTS 插件与原生插件自动集成。普通 uni-app 和 uni-app x（含蒸汽模式）项目都支持。
两个入口
| 自定义基座打包 | App本地打包(正式包) | |
|---|---|---|
| 产物 | Debug APK，供 HBuilderX 真机调试 | 已签名的 Release APK，可分发/上架 |
| Gradle 任务 | assembleDebug |
assembleRelease |
| 前端资源 | 可选生成 | 默认生成（正式包必须用最新资源） |
| 可选输出 | 替换项目 unpackage/debug/ |
复制到项目 unpackage/release/apk/ |
| 调试服务 | 内置 debug-server，支持真机联调 |
不含调试服务，体积更小 |
两者共用同一套项目配置（包名、AppKey、签名证书）；SDK 包按项目自动匹配，多项目/多 SDK 版本切换不需要改全局设置（见「首次配置」）。
特性
- 不排队 — 基座和正式包都在本地用官方离线 SDK 工程编译
- 一键打包 — 模块自动识别、依赖自动注入、权限自动同步，零手动改工程
- 按需裁剪 — 未声明的 provider、源码没用到的内置能力，对应 aar 直接排除；没有 UTS 插件就不引入 Kotlin 运行时
- UTS 插件零配置 — 自动创建原生模块、注册编译器、处理 hooksClass 与组件注册
- 原生插件自动集成 — 本地插件自动复制 aar/jar 并注入 gradle 依赖
- 权限自动注入 — 从 manifest.json 读取声明，去重合并写入 AndroidManifest.xml，支持
excludePermissions强制移除 - 权限审计内置 — 扫描源码 API 调用、manifest 模块与
uni_modules插件，对比打包后实际拥有的权限给出冗余/缺失建议，勾选后写回manifest.json - uni-app x 双通道 — 自动识别
uni-app-x，普通模式用uniappxnativepackage模板，蒸汽模式（vapor: true）自动切到xvnativeproject模板 - 图标与启动图落地原生工程 —
app-android.distribute.icons按密度写入mipmap-*；splashScreens.default写入drawable-*/splash（含 .9.png）作为启动界面图，splashScreens.icon/brand接 Android 12+ SplashScreen 的中部 logo 与底部品牌图，background/background@night为启动背景色。DCloud 的启动图配置只对云打包生效，本地打包由本插件替你写进原生工程；图片支持项目内相对路径与绝对路径 - SDK 包按项目记忆 — 打包对话框内「SDK 包」下拉自动匹配并记住每个项目的选择，同级目录放新版本 SDK 即自动入列，零配置切换
环境要求
首次配置约 10-15 分钟，主要是下载 SDK。
1. Android Studio
插件需要一个 Gradle 编译环境，你不用打开它写代码。安装时会附带 Android SDK（后面「Android SDK 路径」要用）。
2. DCloud Android 离线 SDK（普通 uni-app 项目）
uni-app x Android 原生 SDK：官方下载页（标准版与蒸汽版分开，见下文第 4 节）
解压后的结构：
Android-SDK@xxx/
├── HBuilder-Integrate-AS/ ← 打包工程模板（高级区「SDK 工程目录」，填根目录或它本身均可）
│ └── simpleDemo/ ← 主模块（「SDK 模块名」默认就是它，缺失时自动回退）
└── SDK/
└── libs/ ← 所有 aar（自动从根目录派生，一般无需单独填）
SDK 版本必须和 HBuilderX 版本完全一致。比如 HBuilderX 是 5.07，就下 5.07 对应的离线 SDK，不一致会导致运行时报错。HBuilderX 版本在菜单
帮助 → 关于查看。
3. DCloud uni-app x Android SDK（uni-app x 项目）
打包 uni-app x 项目需要额外下载对应的原生 SDK，目录里应包含 SDK/libs、plugins 以及工程模板：
| 项目模式 | 需要的 SDK | 工程模板 |
|---|---|---|
| 普通 uni-app x | Android-uni-app-x-SDK@xxx |
uniappxnativepackage |
蒸汽模式（manifest.json 里 vapor: true） |
Android-uni-app-x-vapor-SDK@xxx |
xvnativeproject |
两种 SDK 的路径都可以只填一个：插件会在已配置 SDK 的同级目录下自动探测另一种模板（也可都不填，打包时按同级扫描结果自动匹配）。把它们放在同一个父目录（如 G:\apk）即可零配置。
4. JDK
插件按下面的顺序选择 JDK，并在打包日志第一行打印实际使用的版本：
HBuilderX 内置 Java 17 → 全局设置的「JDK 路径」 → 系统 JAVA_HOME
蒸汽模式例外：xvnativeproject 的 auto-register 插件是 Java 21 字节码，至少要 JDK 21，而且模板的 gradle/gradle-daemon-jvm.properties 里钉定了一个具体版本（当前 SDK 钉的是 25）。插件的处理逻辑：
| 本机 JDK | 行为 |
|---|---|
| ≥ 模板钉定版本 | 直接用本机 JDK，保留钉定 |
| 21 ~ 钉定版本之间 | 移除 daemon 钉定改用本机 JDK，并注入 -XX:TieredStopAtLevel=1 -Xmx4096m（规避 JDK 21 上 R8/D8 的 C2 JIT 崩溃） |
| < 21 | 保留钉定，交给 Gradle 联网从 api.foojay.io 下载对应 JDK；网络不通就会失败 |
默认运行时不满足时，插件会自动扫描本机常见安装位置（Program Files\Java、Eclipse Adoptium、Amazon Corretto、Android Studio 的 jbr 等）挑一个 ≥21 的最高版本。
- 普通 uni-app / 非蒸汽 uni-app x：用内置 Java 17 就行，不要填 JDK 8（离线 SDK 要求 11+）
- 蒸汽模式：装一个和模板钉定版本一致的 JDK 最省事（不用联网下载，也不会触发 JIT 规避参数）
首次配置
全局设置
菜单 工具 → Android离线打包工具 → 基座全局设置
全局设置按「一次配置、长期使用」分层，机器级路径在上，普通 uni-app 通道字段收在底部高级区：
| 配置项 | 必填 | 说明 |
|---|---|---|
| APK 输出目录 | 是 | 产物存放位置；留空时若没勾选「复制到项目目录」会无处输出 |
| uni-app x 构建目录 | 否 | 工程副本的存放位置，默认 ~/.smart-pack-debug/uniappx-build。不能含中文，Gradle 对非 ASCII 路径支持不佳，建议填纯英文路径如 D:\build |
| JDK 路径 | 否 | 留空优先用 HBuilderX 内置 Java 17 |
| Android SDK 路径 | 建议填 | 含 platform-tools 的目录，用于生成 local.properties，留空则读环境变量/默认路径 |
| 标准 SDK 根目录 | uni-app x 必填 | Android-uni-app-x-SDK@xxx（含 uniappxnativepackage），注意不是 HBuilder-Integrate-AS |
| 蒸汽 SDK 根目录 | 否 | Android-uni-app-x-vapor-SDK@xxx，留空自动在同级目录探测 |
| 默认 ABI 架构 | 否 | 仅普通 uni-app 通道生效，且 manifest.json 里配了 abiFilters 时以 manifest 为准 |
| 打包后清理构建中间产物 | 否 | 清理工程副本里的 build/、.gradle，可省数 GB 磁盘，代价是下次全量重编 |
| SDK 工程目录 / SDK 完整库目录 / SDK 模块名 | 普通 uni-app 必填 | 高级区字段：HBuilder-Integrate-AS 目录、Android-SDK@xxx/SDK/libs、主模块名（默认 simpleDemo），仅普通 uni-app 项目需要 |
配置文件存放在
~/.smart-pack-debug/config.json。Android SDK 路径虽然标着可选，但强烈建议填。保存时会预检各 SDK 目录的类型特征（如标准根目录必须含uniappxnativepackage），填错当场提示；留空一律放行，由打包时自动探测兜底。
SDK 包按项目自动匹配，无需来回改全局设置：打包对话框里有一个「SDK 包」下拉框。uni-app x 项目蒸汽模式（manifest vapor: true）自动选含 xvnativeproject 的 SDK，非蒸汽自动选含 uniappxnativepackage 的 SDK；普通 uni-app 项目自动选含 HBuilder-Integrate-AS 的 SDK 根目录（工程目录/完整库目录自动派生，模块名自动回退到真实存在的目录）。选择会记忆到项目（sdkRootDir），下次打包直接沿用。把新版本 SDK 解压到已配置 SDK 的同级目录，会自动出现在下拉框里，不必再进全局设置。
项目配置
菜单 工具 → Android离线打包工具 → 基座项目管理 → + 新建项目
| 配置项 | 说明 |
|---|---|
| 项目目录 | 选择后自动读取应用名称、AppID、版本号 |
| 包名 | Android applicationId，如 com.example.app |
| AppKey | DCloud 开发者中心生成的 Android 离线打包 AppKey，须与 AppID、包名、证书 SHA1 完全一致 |
| 证书文件 / Key 别名 / Key 密码 / 证书密码 | 签名证书，基座与正式包共用同一套 |
证书是必填项。没配证书会直接停止打包，不会退回 SDK 模板自带的
test.jks。
使用方式
自定义基座（Debug）
菜单 工具 → Android离线打包工具 → 自定义基座打包，或右键项目 → 自定义基座打包
- 打包前先生成资源 — 调 HBuilderX CLI 重新编译前端资源（需在 HBuilderX 中打开该项目）
- 替换项目自定义基座 — 复制到项目
unpackage/debug/，蒸汽模式文件名android_debug_vapor.apk，否则android_debug.apk
App本地打包（Release 正式包）
菜单 工具 → Android离线打包工具 → App本地打包(正式包)，或右键项目 → App本地打包(正式包)
- 打包前先生成资源 — 默认勾选，正式包必须用最新前端资源
- 复制到项目发布目录 — 额外输出到项目
unpackage/release/apk/，与 HBuilderX 云打包产物位置一致
正式包复用项目配置里的包名、AppKey 和签名证书，不用重复填。
关于正式包的两个默认行为：
- 不开启代码混淆（R8 / minify / shrinkResources 全部关闭）。DCloud 的 aar 没有提供完整 keep 规则，开混淆极易在运行时因反射类被裁掉而崩溃。
- 只打 v2 签名，不打 v1（JAR 签名）。v2 从 Android 7.0（API 24）起支持，minSdk ≥ 24 的项目安装和上架都没问题。如果你的加固平台强制要求 v1，需要自行在注入的
signingConfigs里补v1SigningEnabled true。
权限审计
入口：工具菜单 → Android离线打包工具 → Android权限审计；或在项目里右键 manifest.json / package.json。
审计把两个集合分开：
- 需要的权限 — 基础运行时权限 ∪ 模块需要的权限 ∪ 源码里实际调用的
uni.*API ∪uni_modules插件声明 - 打包后实际拥有的权限 —
manifest.json声明 ∪ 离线打包注入 ∪ 工程AndroidManifest.xml∪ 插件声明，再减去excludePermissions
以第二个集合为基准，是因为离线打包会自行注入权限、SDK aar 也会经 Manifest Merger 带入权限。只比 manifest.json 会把这些都报成"缺失"。
结果分三类：建议补充（打包后仍不具备）、建议精简（manifest.json 里声明了但没检测到使用，可勾选移除）、打包注入但未见使用（来自模块表，要关闭对应模块或写 excludePermissions 才会消失，勾掉 manifest.json 里的同名声明没有用）。
uni-app x 项目走 app-android.distribute 读配置（权限字段比 uni-app 少一层 android），源码扫描覆盖 .uvue / .uts。
产物输出位置
| 场景 | 位置 |
|---|---|
| 未勾选项目内输出 | 「APK 输出目录」下同时生成 {prefix}_{时间戳}.apk（历史版本）和 {prefix}_latest.apk（最新版） |
| 勾选「替换项目自定义基座」 | <项目>/unpackage/debug/android_debug[_vapor].apk |
| 勾选「复制到项目发布目录」 | <项目>/unpackage/release/apk/{prefix}_{时间戳}.apk |
prefix 取自项目配置的 outputPrefix，默认为 AppID 去掉 __UNI__ 后的小写形式。
关于模块和插件
模块无需手动勾选，插件自动从 manifest.json 识别；原生插件和 UTS 插件自动集成。uni-app x 项目会自动识别 uni-app-x 配置并切到独立打包通道。
支持的模块
支付（微信/支付宝/PayPal/Stripe/Google）、登录（微信/QQ/微博/一键登录/Google/Facebook）、分享、推送（UniPush/个推/FCM）、地图（高德/百度/腾讯）、定位（系统/腾讯）、统计（友盟/Google）、扫码、SQLite、指纹、蓝牙、iBeacon、通讯录、直播推流、语音识别、人脸识别、X5 内核等。
本地原生插件自动集成；云端插件会在表单里给出操作指引。
命令列表
| 命令 | 说明 |
|---|---|
| 自定义基座打包 | 生成 Debug 基座，用于 HBuilderX 真机调试 |
| App本地打包(正式包) | 生成已签名的 Release APK，用于分发/上架 |
| 基座项目管理 | 新增、编辑、删除项目配置 |
| 检查SDK更新 | 检测 DCloud 最新 SDK 版本 |
| 基座全局设置 | 配置 SDK 路径、输出目录、JDK 等 |
| Android权限审计 | 扫描项目权限使用情况，给出补充/精简建议并写回 manifest.json |
打包过程在 HBuilderX 底部输出面板实时显示日志（基座和正式包分别是两个独立面板）。
常见问题
Q: 报「SDK location not found」或「缺少 local.properties」？
A: Gradle 找不到 Android SDK。推荐在全局设置里填 Android SDK 路径（含 platform-tools）；或用 Android Studio 打开一次 SDK 工程目录，会自动生成 local.properties。
Q: 更新了 HBuilderX 和离线 SDK 后打包报错？
A: 把新版本 SDK 解压到旧 SDK 的同级目录即可——所有通道（普通 uni-app / 标准 x / 蒸汽 x）的打包对话框「SDK 包」下拉都会自动列出新目录，选一次就记忆到项目，不用改全局设置。填了 Android SDK 路径的话 local.properties 会自动重新生成。
Q: 报「SDK 版本不一致」？ A: 离线 SDK 版本必须和 HBuilderX 版本对齐。
Q: uni-app x 项目提示 SDK 未配置？
A: 全局设置里的「标准 SDK 根目录」要指向 Android-uni-app-x-SDK@xxx（含 uniappxnativepackage），不是普通 uni-app 的 HBuilder-Integrate-AS。若提示里点名了当前配置的目录不含模板，说明它指向了普通 uni-app SDK 或蒸汽 SDK，改正即可；把 SDK 放在已配置 SDK 的同级目录也会被自动识别。
Q: 提示「未找到 uni-app x 蒸汽模式离线 SDK」？
A: 蒸汽项目需要 Android-uni-app-x-vapor-SDK（目录里含 xvnativeproject）。要么在全局设置里显式填写，要么把它和普通 uni-app x SDK 放在同一个父目录下让插件自动探测。
Q: Gradle 报 Unresolved reference 'uniappxv' / UTSAutoRegister？
A: 复用的本地打包资源是蒸汽模式编译的产物，却走了标准通道（或反之），运行时类不通用。插件已会提前拦截；处理：勾选「打包前先生成资源」按当前 manifest 重编，或把「SDK 包」下拉切回匹配模式的 SDK。
Q: 编译失败提示 Java 版本问题？
A: 普通项目填 JDK 17（Android Studio 的 jbr 目录即可）；蒸汽模式需要 JDK 21+，插件会自动扫描本机，扫不到就手动装一个并在全局设置里填路径。
Q: Gradle 报 immutable workspace ... have been modified？
A: 这是 ~/.gradle/caches/<版本>/transforms 缓存损坏（多进程同时构建或被杀进程导致），和插件无关。删掉报错信息里点名的那几个 hash 目录，重跑即可自动重建。
Q: 运行提示「未配置 AppKey 或配置错误」？ A: 打包前会预检查 AppKey、包名、AppID 和证书，缺失直接停止。请核对 AppID、包名、证书 SHA1、DCloud 离线 AppKey 是否与开发者中心完全一致。
Q: 正式包提示「APK 未签名」？
A: 说明 signingConfigs/buildTypes 注入未生效或证书信息有误。检查证书路径是否存在、Key 别名和两个密码是否正确。
Q: 升级插件后自定义基座安装失败，提示签名冲突？
A: 1.1.0 起基座会真正使用你在项目配置里填的证书签名（此前蒸汽模板缺少 buildTypes 块，实际用的是 Android 默认 debug 证书）。签名变了，先卸载手机上的旧基座再装。
Q: 基座运行白屏？
A: 检查 SDK 的 libs 目录下是否有 debug-server-release.aar。
Q: APK 体积太大？
A: 在 manifest.json 里配 abiFilters 只保留需要的架构（arm64-v8a 已覆盖绝大多数在用设备）。uni-app x 通道只读 manifest.json，全局设置里的默认 ABI 对它不生效。另外确认 app-android.distribute.disableLegacyPackaging 没被写成 true —— 这个键按 DCloud 文档默认 false，含义是压缩存放 .so（extractNativeLibs=true），写成 true 会退回不压缩，仅 arm64 一个架构就多出约 5 MB。插件会按该值归一化工程里的 useLegacyPackaging，蒸汽模板里写死的值也一样被覆盖。
Q: 云端原生插件怎么离线打包？
A: 云端插件无法自动集成。去插件市场下载离线版本放进 nativeplugins/，把 isCloud 改成 false 后重新打包。付费/加密插件只支持云打包。
Q: 官方云打包出来的 app 正常，插件打包的部分功能异常？ A: 先用官方打包工具确认问题边界，然后到交流群里说明具体情况，我看到了会回复。也可以直接改源码，里面都有注释。
已知限制
- 只支持 Android，不支持 iOS
- 云端原生插件、付费/加密插件不支持离线打包
- 普通 uni-app 通道需要一个
HBuilder-Integrate-AS工程；uni-app x 通道需要对应的原生 SDK，两者互不复用 - 蒸汽与标准的本地打包资源（含 UTS 编译产物）互不通用，切换模式后需勾选「打包前先生成资源」重编一次
- 构建目录含中文时 Gradle 可能失败，请用纯英文路径
项目介绍
本地一键生成 Android 自定义基座（Debug）和 正式发布包（Release），不用排队等云打包。
https://ext.dcloud.net.cn/plugin?id=30108定制我的领域