更新记录

1.3.4（2026-10-09） 下载此版本

1.3.4（2026-10-07）

变更

• 插件更名为「Android离线打包工具」：插件显示名、工具 菜单标题、打包对话框标题、输出面板横幅与 readme 同步更新。插件 id 与配置目录 ~/.smart-pack-debug 均未变动，升级后项目配置、SDK 记忆和证书设置照常生效，无需迁移

• 1.3.3（2026-10-06）

  新增

• 模式匹配守卫：标准通道复用旧资源打包时，先扫描生成 Kotlin 与 UTS 插件源码中的蒸汽编译特征（io.dcloud.uniappxv / UTSAutoRegister / UTSBridge），命中即拦截并提示「勾选打包前先生成资源」或「切换蒸汽 SDK」，不再白跑一次 Gradle 全量编译后才报 Unresolved reference 'uniappxv'

1.3.2（2026-10-06）

新增

• 全局设置保存预检：各 SDK 路径填了就先校验类型特征，不再等打包时报错——「标准 SDK 根目录」不含 uniappxnativepackage 时当场拦截并识别出实际填的是普通 uni-app SDK 还是蒸汽 SDK；「蒸汽 SDK 根目录」校验 xvnativeproject；高级区「SDK 工程目录」兼容 SDK 根目录或 HBuilder-Integrate-AS 两种填法；Android SDK 校验 platform-tools；JDK 校验 bin 目录；完整库目录校验存在性。所有字段留空一律放行（打包时仍有同级自动探测兜底）

1.3.1（2026-10-06）

修复

• 蒸汽项目被打包前预检误判为标准模式：预检把 readManifest 摘要（不含 uni-app-x 键）传给了蒸汽判定，导致蒸汽项目报「未找到标准 uni-app x 离线 SDK」。解析器改为省略 manifest 时自行读取原始文件

新增

• 普通 uni-app（非 x）项目同样接入打包对话框「SDK 包」下拉：候选 = 已配置路径同级目录下含 HBuilder-Integrate-AS 的 SDK 包，选择记忆到项目 sdkRootDir，多项目不再来回改全局高级区
• SDK 工程目录取值容错：填成 SDK 根目录或 HBuilder-Integrate-AS 均可识别；完整库目录自动从根目录派生 SDK/libs
• SDK 模块名按 项目 → 全局 → simpleDemo 顺序取第一个真实存在的目录，全局值失效（如指向蒸汽模板的残留）不再导致打包中途失败
• 普通 uni-app 通道新增早失败守卫：SDK 工程目录/模块目录无效时立即报明确错误并指引修改入口，不再走到中途才失败

1.3.0（2026-10-06）

新增

• 打包对话框新增「SDK 包」下拉框（仅 uni-app x 项目）：蒸汽项目自动选含 xvnativeproject 的 SDK，普通 uni-app x 项目自动选含 uniappxnativepackage 的 SDK；候选包含全局配置的两个根目录及其同级目录自动扫描结果，新版本 SDK 解压到同级目录即自动入列
• 下拉选择会记忆到项目配置（sdkRootDir），下次打包直接沿用；保持默认选择时不写配置
• 项目 appId/appName 加载时自动清理首尾空白，修复历史配置中换行符污染构建目录名与 AndroidManifest 的问题

优化

• 全局设置重排为「通用路径 / uni-app x SDK 包 / 构建选项 / 高级：普通 uni-app 通道」四区，机器级配置一次填完长期使用；普通 uni-app 独占的 SDK 工程目录、完整库目录、模块名收进底部高级区
• uni-app x 通道不再读取「SDK 工程目录」「SDK 完整库目录」：gradle-wrapper.jar 改从解析出的 SDK 根目录同级扫描（旧字段仅作兜底），对话框版本号改从 SDK 根目录名解析，多项目切换不再需要来回改全局设置
• 移除全局设置对「SDK 工程目录」的必填校验，改为打包时按项目通道分别校验；标准 uni-app x SDK 缺失（如根目录误指向普通 uni-app SDK）时给出含同级目录指引的明确报错

1.2.1（2026-10-06）

修复

• 权限审计误报「建议移除」：UTS 插件在 utssdk 源码里用字符串字面量申请权限（如 permissions.push("android.permission.BLUETOOTH_CONNECT")）此前完全不被识别，蓝牙等权限会被判为冗余。新增两类证据来源：源码中的 android.permission.X / Manifest.permission.X 字面量，以及 android.* 原生包名推断
• 插件引用检测漏扫业务代码：原先只扫固定的 pages / common / store / components 等根目录，unibest 这类把业务代码放在 src/ 下的项目一个文件都扫不到，插件被误判为「未引用」。改为整项目遍历后按排除集过滤，并同时识别 src/pages.json
• 已安装但未被引用的插件，其 AndroidManifest.xml 与源码声明的权限也计入「需要」，避免只删 manifest.json 声明就让插件功能失效

新增

• 报告单独列出「仅插件申请、业务代码与模块表未命中」的权限，说明其不参与精简建议

1.2.0（2026-10-06）

新增

• 「Android权限审计」命令：入口在 工具菜单 与 项目右键（选中 manifest.json / package.json）。扫描业务源码 API 调用、manifest 模块、uni_modules 插件，输出冗余与缺失权限，支持勾选后写回 manifest.json
• 审计基准为打包后实际拥有的权限：manifest.json 声明 ∪ 离线打包注入 ∪ 工程 AndroidManifest.xml ∪ 插件声明 − excludePermissions。只比 manifest.json 会把 SDK aar 自带和打包注入的权限误报为"缺失"
• 同时支持 uni-app 与 uni-app x：uni-app x 读 app-android.distribute（权限字段比 uni-app 少一层 android），源码扫描覆盖 .uvue / .uts，插件引用探测覆盖 App.uvue / main.uts

优化

• 模块→权限映射收敛为唯一数据源 src/perm/modulePermissions.js，原先分散在 packer.js、uniAppXPacker.js 与权限审计插件中的多份副本全部删除
• 每个模块区分「打包注入集」与「审计需要集」，并维持"需要集 ⊇ 注入集"不变式（加载时校验），避免审计建议删除的权限被下次打包重新注入
• uses-permission 与 uses-feature 分开解析，此前硬件特性会被当作权限参与精简
• JSON 注释剥离统一到 src/jsonc.js

说明

• 迁移经过逐行比对验证：46 个模块 key、全量合并集、5 个真实项目（含 2 个 uni-app x）的权限注入与硬件特性输出与迁移前完全一致，打包产物不变

1.1.0（2026-10-02）

新增

• 新增「App本地打包(正式包)」命令：走官方离线 SDK 工程编译 Release APK，普通 uni-app 与 uni-app x（含蒸汽模式）两条通道均支持
• 正式包可选复制到项目 unpackage/release/apk/，与 HBuilderX 云打包产物位置一致
• 正式包复用项目配置中的包名、AppKey、签名证书，无需重复填写；统一不启用代码混淆（R8/minify）
• 打包表单按模式区分选项：正式包默认勾选「打包前先生成资源」，隐藏「替换项目自定义基座」

平台兼容性

Android本地打包工具

本地一键生成 Android 自定义基座（Debug） 和 正式发布包（Release），不用排队等云打包。

选项目 → 点打包，剩下的交给插件：模块自动识别、依赖自动注入、权限自动同步、UTS 插件与原生插件自动集成。普通 uni-app 和 uni-app x（含蒸汽模式）项目都支持。

两个入口

两者共用同一套项目配置（包名、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 模板
• SDK 包按项目记忆 — 打包对话框内「SDK 包」下拉自动匹配并记住每个项目的选择，同级目录放新版本 SDK 即自动入列，零配置切换

环境要求

首次配置约 10-15 分钟，主要是下载 SDK。

1. Android Studio

插件需要一个 Gradle 编译环境，你不用打开它写代码。安装时会附带 Android SDK（后面「Android SDK 路径」要用）。

下载：Android Studio 官网

2. DCloud Android 离线 SDK（普通 uni-app 项目）

下载：DCloud 离线 SDK 下载页

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 的路径都可以只填一个：插件会在已配置 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）。插件的处理逻辑：

默认运行时不满足时，插件会自动扫描本机常见安装位置（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 通道字段收在底部高级区：

配置文件存放在 ~/.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离线打包工具 → 基座项目管理 → + 新建项目

证书是必填项。没配证书会直接停止打包，不会退回 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。

产物输出位置

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 内核等。

本地原生插件自动集成；云端插件会在表单里给出操作指引。

命令列表

打包过程在 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 对它不生效。

Q: 云端原生插件怎么离线打包？ A: 云端插件无法自动集成。去插件市场下载离线版本放进 nativeplugins/，把 isCloud 改成 false 后重新打包。付费/加密插件只支持云打包。

Q: 官方云打包出来的 app 正常，插件打包的部分功能异常？ A: 先用官方打包工具确认问题边界，然后到交流群里说明具体情况，我看到了会回复。也可以直接改源码，里面都有注释。

已知限制

• 只支持 Android，不支持 iOS
• 云端原生插件、付费/加密插件不支持离线打包
• 普通 uni-app 通道需要一个 HBuilder-Integrate-AS 工程；uni-app x 通道需要对应的原生 SDK，两者互不复用
• 蒸汽与标准的本地打包资源（含 UTS 编译产物）互不通用，切换模式后需勾选「打包前先生成资源」重编一次
• 构建目录含中文时 Gradle 可能失败，请用纯英文路径