uni-app 对接自定义 JAR:Android 原生插件、AAR、离线打包与云打包完整实战
摘要: 本文从零讲清楚 uni-app 如何通过 Android 原生插件调用厂家 JAR,并最终生成可以安装到真实设备上的 APK。内容覆盖 HBuilderX、DCloud Android 离线 SDK、Android Studio、UniModule、AAR/JAR 依赖、AppID、AppKey、签名、ABI、自定义基座、云打包、设备服务层、AIDL 生命周期、APK 验包、旧 Android 设备兼容和真机验收。文中的流程来自真实设备项目,项目身份和厂家信息均已脱敏。
关键词: uni-app、Android 原生插件、自定义 JAR、UniModule、AAR、HBuilderX、DCloud 离线打包、自定义基座、云打包、AppKey、APK 签名、armeabi-v7a
适合读者: 第一次接触 uni-app 原生插件,需要对接厂家硬件 SDK、设备控制 JAR 或 Android 系统能力的前端与全栈开发者。
版本说明: 最后修订于 2026-07-17。DCloud 离线 SDK、Android Gradle Plugin 和 HBuilderX 的目录或配置可能随版本变化;本文强调的是稳定方法,具体依赖文件名以对应版本的官方示例工程为准。
图表说明: 本文流程图使用 Mermaid。CSDN 编辑器若未自动渲染,可先在支持 Mermaid 的 Markdown 编辑器中导出为 PNG,再上传替换对应代码块;图题和正文不需要修改。
文章目录
- uni-app 对接自定义 JAR:Android 原生插件、AAR、离线打包与云打包完整实战
-
- 1. 前言:这篇文章要解决什么问题
-
- 1.1 本文采用的脱敏实测基线
- 1.2 推荐阅读与实践路线
- 2. 开始前必须理解的基础名词
-
- 2.1 APK
- 2.2 JAR
- 2.3 AAR
- 2.4 Module
- 2.5 Android 宿主
- 2.6 Gradle
- 2.7 build.gradle
- 2.8 AIDL
- 2.9 签名、证书与 keystore
- 2.10 AppKey
- 2.11 Runtime 与自定义基座
- 2.12 HBuilderX
- 2.13 两次构建与五层调用
- 3. 通用前置准备:两种打包路线都要完成
-
- 3.1 第 1 步:安装 HBuilderX
- 3.2 第 2 步:安装 Android Studio
- 3.3 第 3 步:下载匹配版本的 DCloud Android 离线 SDK
- 3.4 第 4 步:收集厂家资料和设备信息
- 3.5 第 5 步:在 HBuilderX 新建项目并获取 AppID
- 3.6 第 6 步:在 DCloud 后台创建证书
- 3.7 第 7 步:确定 Android 包名
- 3.8 第 8 步:在 DCloud 后台生成离线 AppKey
- 3.9 第 9 步:准备工作区外的私有签名位置
- 4. 路线一:Android Studio 离线打包(推荐先走通)
-
- 4.1 搭建 Android 宿主
-
- 第 10 步:导入示例工程
- 第 11 步:跑通官方 Demo 确认环境
- 第 12 步:复制一份作为项目专用宿主
- 第 13 步:配置 local.properties
- 第 14 步:配置 app/build.gradle
- 第 15 步:验证签名配置
- 第 16 步:配置 AndroidManifest.xml 的 AppKey
- 第 17 步:配置 dcloud_control.xml
- 4.2 创建原生插件 Module
-
- 第 18 步:新建 Android Library Module
- 第 19 步:配置 Module 的 build.gradle
- 第 20 步:配置混淆文件
- 第 21 步:写最小 sayHi 方法
- 第 22 步:注册插件到 dcloud_uniplugins.json
- 第 23 步:让宿主引用你的 Module
- 第 24 步:编译验证
- 4.3 打通 JavaScript 到 Java 的最小调用链
-
- 第 25 步:在 HBuilderX 写测试页面
- 第 26 步:生成本地打包资源
- 第 27 步:复制资源到 Android 宿主
- 第 28 步:构建 Debug APK
- 第 29 步:连接手机并运行
- 第 30 步:验证 sayHi
- 4.4 引入厂家 JAR
-
- 第 31 步:把 jar 包放到 libs 目录
- 第 32 步:用 javap 查看方法签名
- 第 33 步:明确厂家 JAR 的编译期和运行时归属
- 第 34 步:写 getDeviceInfo 只读方法
- AIDL / Service 生命周期不能照抄一行绑定
- 第 35 步:编译验证
- 第 36 步:验证 jar 包进了 APK
- 第 37 步:前端加 getDeviceInfo 按钮
- 第 38 步:重新生成资源 + 复制 + 构建
- 第 39 步:普通手机验证
- 4.5 在目标设备上完成真机验证
-
- 第 40 步:准备 U 盘安装包
- 第 41 步:检查 APK 和目标设备兼容性
- 第 42 步:在目标设备上安装和验证
- 4.6 路线一的日常开发循环
- 5. 路线二:本地原生插件、自定义基座与云打包
-
- 5.1 切换云打包前的条件
- 5.2 编译插件 AAR
-
- 云打包第 1 步:编译 AAR
- 云打包第 2 步:检查 AAR 与厂家 JAR 归属
- 5.3 配置 uni-app 本地插件目录
-
- 云打包第 3 步:创建插件目录
- 云打包第 4 步:创建 package.json
- 云打包第 5 步:在 manifest.json 引入插件
- 5.4 制作自定义调试基座
-
- 云打包第 6 步:打自定义调试基座
- 云打包第 7 步:运行自定义基座
- 5.5 验证插件并执行正式云打包
-
- 云打包第 8 步:验证功能
- 云打包第 9 步:正式云打包出 APK
- 5.6 路线二的日常开发循环
- 5.7 云打包常见问题
- 6. 正式工程设计:业务页面不要直接调用原生插件
-
- 6.1 统一结果模型
- 6.2 原生适配器:Promise、超时和一次回调
- 6.3 不支持平台适配器
- 6.4 正式调用时序
- 7. 原生插件接口设计规则
-
- 7.1 参数在 JavaScript 和原生两层校验
- 7.2 线程与回调
- 7.3 生命周期和资源释放
- 7.4 权限与设备特性
- 7.5 高风险能力分级
- 8. Android Studio 离线打包与 HBuilderX 云打包对比
- 9. 真实设备项目中的实测结论与适用边界
-
- 9.1 为什么要按 Step 逐层增加变量
- 9.2 截图等“不可靠返回值”的判定模型
- 10. APK 构建后的静态校验与发布门禁
-
- 10.1 校验包名、版本、SDK 与 ABI
- 10.2 校验最终 APK 签名
- 10.3 校验 ZIP 对齐与文件哈希
- 10.4 检查页面资源、插件类和厂家类
- 10.5 使用 ADB 安装并获取真实错误码
- 11. 真机验收矩阵:什么才算真正通过
-
- 11.1 基础链路
- 11.2 写操作和真实设备行为
- 11.3 正式交付候选包
- 12. 常见问题与分层排障
-
- 先按故障阶段分流
- HBuilderX 只生成 resources,没有 APK
- AppKey 校验失败
- 安装提示签名不一致
- 无法覆盖升级
- `Duplicate class`
- `JAVA_HOME` 未设置或 JDK 不兼容
- Android 5.x 只显示“应用未安装”
- `NoClassDefFoundError`
- `NoSuchMethodError`
- `requireNativePlugin()` 返回空或方法不存在
- 启动页正常,进入首页后只剩背景
- 方法调用成功,但目标设备没有动作
- Release 构建被 targetSdk Lint 拦截
- Java 报 `非法字符: '\\ufeff'`
- 13. 总结:从“能编译”走到“能交付”
1. 前言:这篇文章要解决什么问题
这篇文章从安装工具开始,一步步把一个空的 uni-app 项目变成能安装、能调用厂家 JAR、能定位故障并具备交付证据的 Android APK。
你不需要有任何 Android 开发经验,只要按顺序照做,每一步都告诉你"做什么、怎么做、为什么这么做"。遇到坑的地方会提前提醒。
整个指南分两条路线:
- 路线一:离线打包——适合自己一个人全包(既写前端又写 Java),改 Java 代码调试快,推荐新手用
- 路线二:云打包——适合 Java 插件写好调通后,交给前端同事使用,或者你只想用 HBuilderX 不开 Android Studio
两条路线共用第 1 到第 9 步的环境、应用身份和证书准备,从第 10 步开始分叉。建议新手先走路线一,把源码 Module、JAR 和目标设备跑通,再制作 AAR 走路线二。
完成全文实践后的最低成果不是一句“编译成功”,而是以下证据都成立:
- 最终 APK 的 AppID、包名、签名、AppKey 和版本可以核对。
- uni.requireNativePlugin() 能调用一个无副作用 Java 方法并收到一次回调。
- 厂家 JAR 的类确实进入最终 APK,且没有重复类。
- 至少一个厂家只读方法在目标设备返回可信数据。
- 安装、冷启动、前后台切换、进程重启和异常分支有验证记录。
- 正式证书、密码、Token 和厂家授权文件没有进入 Git 仓库。
文章很长,第一次实践时不要跳步,尤其不要跳过最小桥接、最终 APK 签名和 ABI 检查。
1.1 本文采用的脱敏实测基线
本文的流程和结论来自一个已经在真实班牌设备上完成验证的项目,但发布版对项目、厂家、证书和设备身份全部做了脱敏。以下名称只用于教学,不能直接复制为生产身份:
| 项目目录 | C:\\workspace\\ClassBoardDemo | 教学示例路径 |
| uni-app AppID | __UNI__A1B2C3D | 脱敏示例,换成自己的 AppID |
| Android 包名 | com.example.classboard | 脱敏示例,正式项目应使用自有域名反写 |
| Java 插件包 | com.example.device | 源码命名空间,可与应用包名不同 |
| 插件 ID | DemoDevicePlugin | 必须与前端调用名一致 |
| 厂家入口 | com.vendor.device.DeviceManager | 占位名,以实际 JAR 为准 |
| 厂家 JAR | vendor-device-sdk.jar | 文件名、大小、哈希只写入私有项目记录 |
| 目标设备 | VendorBoard-A / 嵌入式 Android 终端 / API 21+ | 脱敏的横屏全高清规格的嵌入式终端 |
| 目标 ABI | armeabi-v7a | 设备是 32 位 ARMv7 |
| 最低 SDK | 21 | 当前宿主配置 |
| 开发工具链 | HBuilderX 5.15 页面资源 + DCloud 5.14 本地宿主 | 仅用于开发快速迭代,存在已知错配 |
| 最终交付工具链 | 匹配 HBuilderX 5.15 的正式 Runtime 云包 | 必须重新全量真机回归 |
| 本地插件交付 | 薄 AAR + android/libs/vendor-device-sdk.jar | 厂家 JAR 只保留一份,不嵌入 AAR |
当前已经获得的真机结论:
- Step 0:最小页面、App-Plus 资源、本地宿主、正式身份签名 APK、U 盘安装和点击交互通过。
- Step 3:uni-app → UniModule → 厂家 JAR → 目标固件链路通过,设备信息、显示、网络、导航栏和定时计划等能力可调用。
- 定时开关机:设置、回读、真实关机以及关机后的计划自动开机通过。
- 截图:文件生成和打开通过;厂家布尔返回值可能为 false,成功必须按文件是否新增/更新、非空且可打开判断。
- Step 4:Android 标准 Camera 枚举、实时预览、1280 × 720 JPEG 保存、媒体扫描和系统图库查看通过;厂家 JAR 本身没有摄像头 API。
- Step 5:默认 Launcher、重启自动进入本项目、系统 Launcher3 恢复、导航栏隐藏/恢复和厂家开机动画替换通过。
- 静默安装:厂家命令接受、包名和签名检查通过;使用更高 versionCode 完成真实升级、进程恢复和配置保留仍待交付前补测。
图 1:脱敏项目从最小安装到正式交付的阶段路线
#mermaid-svg-CJxJJD7a302sW5g6{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-CJxJJD7a302sW5g6 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-CJxJJD7a302sW5g6 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-CJxJJD7a302sW5g6 .error-icon{fill:#552222;}#mermaid-svg-CJxJJD7a302sW5g6 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-CJxJJD7a302sW5g6 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-CJxJJD7a302sW5g6 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-CJxJJD7a302sW5g6 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-CJxJJD7a302sW5g6 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-CJxJJD7a302sW5g6 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-CJxJJD7a302sW5g6 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-CJxJJD7a302sW5g6 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-CJxJJD7a302sW5g6 .marker.cross{stroke:#333333;}#mermaid-svg-CJxJJD7a302sW5g6 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-CJxJJD7a302sW5g6 p{margin:0;}#mermaid-svg-CJxJJD7a302sW5g6 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-CJxJJD7a302sW5g6 .cluster-label text{fill:#333;}#mermaid-svg-CJxJJD7a302sW5g6 .cluster-label span{color:#333;}#mermaid-svg-CJxJJD7a302sW5g6 .cluster-label span p{background-color:transparent;}#mermaid-svg-CJxJJD7a302sW5g6 .label text,#mermaid-svg-CJxJJD7a302sW5g6 span{fill:#333;color:#333;}#mermaid-svg-CJxJJD7a302sW5g6 .node rect,#mermaid-svg-CJxJJD7a302sW5g6 .node circle,#mermaid-svg-CJxJJD7a302sW5g6 .node ellipse,#mermaid-svg-CJxJJD7a302sW5g6 .node polygon,#mermaid-svg-CJxJJD7a302sW5g6 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-CJxJJD7a302sW5g6 .rough-node .label text,#mermaid-svg-CJxJJD7a302sW5g6 .node .label text,#mermaid-svg-CJxJJD7a302sW5g6 .image-shape .label,#mermaid-svg-CJxJJD7a302sW5g6 .icon-shape .label{text-anchor:middle;}#mermaid-svg-CJxJJD7a302sW5g6 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-CJxJJD7a302sW5g6 .rough-node .label,#mermaid-svg-CJxJJD7a302sW5g6 .node .label,#mermaid-svg-CJxJJD7a302sW5g6 .image-shape .label,#mermaid-svg-CJxJJD7a302sW5g6 .icon-shape .label{text-align:center;}#mermaid-svg-CJxJJD7a302sW5g6 .node.clickable{cursor:pointer;}#mermaid-svg-CJxJJD7a302sW5g6 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-CJxJJD7a302sW5g6 .arrowheadPath{fill:#333333;}#mermaid-svg-CJxJJD7a302sW5g6 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-CJxJJD7a302sW5g6 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-CJxJJD7a302sW5g6 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-CJxJJD7a302sW5g6 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-CJxJJD7a302sW5g6 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-CJxJJD7a302sW5g6 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-CJxJJD7a302sW5g6 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-CJxJJD7a302sW5g6 .cluster text{fill:#333;}#mermaid-svg-CJxJJD7a302sW5g6 .cluster span{color:#333;}#mermaid-svg-CJxJJD7a302sW5g6 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-CJxJJD7a302sW5g6 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-CJxJJD7a302sW5g6 rect.text{fill:none;stroke-width:0;}#mermaid-svg-CJxJJD7a302sW5g6 .icon-shape,#mermaid-svg-CJxJJD7a302sW5g6 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-CJxJJD7a302sW5g6 .icon-shape p,#mermaid-svg-CJxJJD7a302sW5g6 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-CJxJJD7a302sW5g6 .icon-shape .label rect,#mermaid-svg-CJxJJD7a302sW5g6 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-CJxJJD7a302sW5g6 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-CJxJJD7a302sW5g6 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-CJxJJD7a302sW5g6 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
Step 0最小安装基线真机通过
Step 3厂家 JAR 与核心设备能力真机通过
Step 4Android Camera/JPEG真机通过
Step 5Launcher/开机动画真机通过
Step 6正式页面迁移与后端闭环当前主线
Step 75.15 正式 Runtime全量回归与交付
文中带“脱敏项目实测”的结论只对当时的 32 位 ARMv7 设备、固件和厂家 SDK 成立;复制到其他设备时必须重新验证。带“通用规则”的内容可以复用,但目录名和依赖版本仍以对应 DCloud 官方示例为准。
1.2 推荐阅读与实践路线
图 2:离线打包与云打包的选择路径
#mermaid-svg-pJPGQnJLAJV9aXIf{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-pJPGQnJLAJV9aXIf .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-pJPGQnJLAJV9aXIf .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-pJPGQnJLAJV9aXIf .error-icon{fill:#552222;}#mermaid-svg-pJPGQnJLAJV9aXIf .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-pJPGQnJLAJV9aXIf .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-pJPGQnJLAJV9aXIf .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-pJPGQnJLAJV9aXIf .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-pJPGQnJLAJV9aXIf .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-pJPGQnJLAJV9aXIf .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-pJPGQnJLAJV9aXIf .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-pJPGQnJLAJV9aXIf .marker{fill:#333333;stroke:#333333;}#mermaid-svg-pJPGQnJLAJV9aXIf .marker.cross{stroke:#333333;}#mermaid-svg-pJPGQnJLAJV9aXIf svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-pJPGQnJLAJV9aXIf p{margin:0;}#mermaid-svg-pJPGQnJLAJV9aXIf .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-pJPGQnJLAJV9aXIf .cluster-label text{fill:#333;}#mermaid-svg-pJPGQnJLAJV9aXIf .cluster-label span{color:#333;}#mermaid-svg-pJPGQnJLAJV9aXIf .cluster-label span p{background-color:transparent;}#mermaid-svg-pJPGQnJLAJV9aXIf .label text,#mermaid-svg-pJPGQnJLAJV9aXIf span{fill:#333;color:#333;}#mermaid-svg-pJPGQnJLAJV9aXIf .node rect,#mermaid-svg-pJPGQnJLAJV9aXIf .node circle,#mermaid-svg-pJPGQnJLAJV9aXIf .node ellipse,#mermaid-svg-pJPGQnJLAJV9aXIf .node polygon,#mermaid-svg-pJPGQnJLAJV9aXIf .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-pJPGQnJLAJV9aXIf .rough-node .label text,#mermaid-svg-pJPGQnJLAJV9aXIf .node .label text,#mermaid-svg-pJPGQnJLAJV9aXIf .image-shape .label,#mermaid-svg-pJPGQnJLAJV9aXIf .icon-shape .label{text-anchor:middle;}#mermaid-svg-pJPGQnJLAJV9aXIf .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-pJPGQnJLAJV9aXIf .rough-node .label,#mermaid-svg-pJPGQnJLAJV9aXIf .node .label,#mermaid-svg-pJPGQnJLAJV9aXIf .image-shape .label,#mermaid-svg-pJPGQnJLAJV9aXIf .icon-shape .label{text-align:center;}#mermaid-svg-pJPGQnJLAJV9aXIf .node.clickable{cursor:pointer;}#mermaid-svg-pJPGQnJLAJV9aXIf .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-pJPGQnJLAJV9aXIf .arrowheadPath{fill:#333333;}#mermaid-svg-pJPGQnJLAJV9aXIf .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-pJPGQnJLAJV9aXIf .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-pJPGQnJLAJV9aXIf .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-pJPGQnJLAJV9aXIf .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-pJPGQnJLAJV9aXIf .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-pJPGQnJLAJV9aXIf .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-pJPGQnJLAJV9aXIf .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-pJPGQnJLAJV9aXIf .cluster text{fill:#333;}#mermaid-svg-pJPGQnJLAJV9aXIf .cluster span{color:#333;}#mermaid-svg-pJPGQnJLAJV9aXIf div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-pJPGQnJLAJV9aXIf .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-pJPGQnJLAJV9aXIf rect.text{fill:none;stroke-width:0;}#mermaid-svg-pJPGQnJLAJV9aXIf .icon-shape,#mermaid-svg-pJPGQnJLAJV9aXIf .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-pJPGQnJLAJV9aXIf .icon-shape p,#mermaid-svg-pJPGQnJLAJV9aXIf .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-pJPGQnJLAJV9aXIf .icon-shape .label rect,#mermaid-svg-pJPGQnJLAJV9aXIf .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-pJPGQnJLAJV9aXIf .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-pJPGQnJLAJV9aXIf .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-pJPGQnJLAJV9aXIf :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
是
否,已有稳定 AAR
先完成第 1 到第 9 步固定工具链与应用身份
Java 插件是否仍在开发或排障?
路线一:Android Studio 离线宿主源码 Module + 本地 JAR
路线二:HBuilderX 本地原生插件自定义基座 + 云打包
普通手机验证桥接
厂家设备验证固件能力
冻结插件版本并产出 AAR
正式候选 APK 全量回归
路线一和路线二可以产出功能相同的 APK,但两边的 Runtime、依赖合并、权限、签名和混淆过程不同。不能拿路线一的通过结果直接替代路线二正式包的回归结果。
2. 开始前必须理解的基础名词
在开始之前,先把反复出现的几个词讲透。第一次接触原生插件时建议完整阅读;已经熟悉 Android 构建体系的读者可以快速浏览。
2.1 APK
APK 就是安卓手机的安装文件,后缀名 .apk。你在应用商店点"下载",下载的就是这个。APK 是最终目标——所有工作都是为了产出这个能装到手机上的文件。
2.2 JAR
后缀名 .jar,主要包含已编译的 Java 字节码,也可能包含配置文件。厂家给的 vendor-device-sdk.jar 提供设备 API,应用通常不改它,而是在自己的 Android Module 中封装它。JAR 不包含 Android 资源;如果厂家还给了 .so、AAR、AIDL、License 或资源文件,这些也必须按文档一起集成,不能只复制 JAR。
2.3 AAR
后缀名 .aar,本质上是 ZIP,可以包含 classes.jar、Android Manifest、资源、ProGuard 规则和本地库。DCloud Runtime 的 AAR 是插件编译时的接口依赖,通常由宿主提供,插件侧应按官方示例使用 compileOnly,避免重复打包。走云打包路线时,需要把自己的 Module 编译为 AAR,并明确厂家 JAR 是嵌入 AAR,还是作为插件目录中的独立依赖,只能选一种归属。
2.4 Module
Android Studio 项目里的“独立零件”。一个项目可以包含多个 Module,各干各的,最后拼到一起。本文新建一个叫 demo_device 的 Module,专门封装厂家 JAR。
2.5 Android 宿主
“宿主"是 Android Studio 里的 app 工程,就是一个空壳 Android 项目。它的作用是装载你的 uniapp 页面和原生插件,最后打包成 APK。 你可以把它当成一个"盘子”——你的前端页面是菜,Java 插件是调料,全部装到这个盘子里,编译端上桌。
2.6 Gradle
Gradle 是一个自动化编译工具。你写好规则(build.gradle 文件),它就自动帮你下载依赖、编译代码、打包成 APK。它就是那个把"盘子里的所有东西"组装成 APK 的机器。
2.7 build.gradle
build.gradle 是 Gradle 的"配方文件",告诉 Gradle 怎么干活、依赖什么、用哪个证书签名。你在教程里反复改的就是这个文件,改完要点"Sync Now"让 Gradle 重新读。
2.8 AIDL
AIDL 是 Android 的跨进程通信机制。有些硬件能力(关机、定时开关机)由系统级服务处理,和你的 App 不在同一个进程。你想调用这些能力,就得通过 AIDL 和系统服务"对话"。把它当成你和对讲机——你说话(AIDL 调用),物业(系统服务)听到后帮你做事。
2.9 签名、证书与 keystore
签名就是给 APK 盖公章,证明这个 APK 是你做的、没被篡改。盖公章用的"印章"就是证书,证书存在 keystore 文件里。 同一个包名的 App,只有签名一样才能覆盖升级——换证书就装不上旧版本的覆盖更新了。
2.10 AppKey
AppKey 是 DCloud 给你的一串许可证字符串。APK 启动时 DCloud 运行时会检查这个 AppKey,对不上就拒绝启动。 它绑定了"AppID + 包名 + 证书 SHA-1"三者,任何一个对不上就失效。
2.11 Runtime 与自定义基座
Runtime 是运行 uni-app 页面和原生插件的 Android 运行时。自定义基座是在 Runtime 中加入本地原生插件后生成的开发 APK。标准基座不包含你新增的插件,H5 也不能验证 Android JAR 能力。
2.12 HBuilderX
DCloud 出的 uni-app 开发工具。走离线本地打包时,“生成本地打包 App 资源”只得到 www;走云打包时,HBuilderX 可以提交构建并下载 APK。不要把“本地资源导出”和“云端 APK 打包”混为一件事。
2.13 两次构建与五层调用
走 Android Studio 离线打包时,需要两段构建:
图 3:离线 APK 的两段构建过程
#mermaid-svg-wNM1uF8cXRisy9KP{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-wNM1uF8cXRisy9KP .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-wNM1uF8cXRisy9KP .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-wNM1uF8cXRisy9KP .error-icon{fill:#552222;}#mermaid-svg-wNM1uF8cXRisy9KP .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-wNM1uF8cXRisy9KP .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-wNM1uF8cXRisy9KP .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-wNM1uF8cXRisy9KP .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-wNM1uF8cXRisy9KP .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-wNM1uF8cXRisy9KP .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-wNM1uF8cXRisy9KP .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-wNM1uF8cXRisy9KP .marker{fill:#333333;stroke:#333333;}#mermaid-svg-wNM1uF8cXRisy9KP .marker.cross{stroke:#333333;}#mermaid-svg-wNM1uF8cXRisy9KP svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-wNM1uF8cXRisy9KP p{margin:0;}#mermaid-svg-wNM1uF8cXRisy9KP .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-wNM1uF8cXRisy9KP .cluster-label text{fill:#333;}#mermaid-svg-wNM1uF8cXRisy9KP .cluster-label span{color:#333;}#mermaid-svg-wNM1uF8cXRisy9KP .cluster-label span p{background-color:transparent;}#mermaid-svg-wNM1uF8cXRisy9KP .label text,#mermaid-svg-wNM1uF8cXRisy9KP span{fill:#333;color:#333;}#mermaid-svg-wNM1uF8cXRisy9KP .node rect,#mermaid-svg-wNM1uF8cXRisy9KP .node circle,#mermaid-svg-wNM1uF8cXRisy9KP .node ellipse,#mermaid-svg-wNM1uF8cXRisy9KP .node polygon,#mermaid-svg-wNM1uF8cXRisy9KP .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-wNM1uF8cXRisy9KP .rough-node .label text,#mermaid-svg-wNM1uF8cXRisy9KP .node .label text,#mermaid-svg-wNM1uF8cXRisy9KP .image-shape .label,#mermaid-svg-wNM1uF8cXRisy9KP .icon-shape .label{text-anchor:middle;}#mermaid-svg-wNM1uF8cXRisy9KP .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-wNM1uF8cXRisy9KP .rough-node .label,#mermaid-svg-wNM1uF8cXRisy9KP .node .label,#mermaid-svg-wNM1uF8cXRisy9KP .image-shape .label,#mermaid-svg-wNM1uF8cXRisy9KP .icon-shape .label{text-align:center;}#mermaid-svg-wNM1uF8cXRisy9KP .node.clickable{cursor:pointer;}#mermaid-svg-wNM1uF8cXRisy9KP .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-wNM1uF8cXRisy9KP .arrowheadPath{fill:#333333;}#mermaid-svg-wNM1uF8cXRisy9KP .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-wNM1uF8cXRisy9KP .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-wNM1uF8cXRisy9KP .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-wNM1uF8cXRisy9KP .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-wNM1uF8cXRisy9KP .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-wNM1uF8cXRisy9KP .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-wNM1uF8cXRisy9KP .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-wNM1uF8cXRisy9KP .cluster text{fill:#333;}#mermaid-svg-wNM1uF8cXRisy9KP .cluster span{color:#333;}#mermaid-svg-wNM1uF8cXRisy9KP div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-wNM1uF8cXRisy9KP .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-wNM1uF8cXRisy9KP rect.text{fill:none;stroke-width:0;}#mermaid-svg-wNM1uF8cXRisy9KP .icon-shape,#mermaid-svg-wNM1uF8cXRisy9KP .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-wNM1uF8cXRisy9KP .icon-shape p,#mermaid-svg-wNM1uF8cXRisy9KP .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-wNM1uF8cXRisy9KP .icon-shape .label rect,#mermaid-svg-wNM1uF8cXRisy9KP .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-wNM1uF8cXRisy9KP .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-wNM1uF8cXRisy9KP .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-wNM1uF8cXRisy9KP :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
第1段:HBuilderX 生成 www 资源
复制到 Android 宿主
第2段:Gradle 编译
uniapp 项目HBuilderX 写的前端页面
www 文件夹
Android Studio 宿主工程
APK
调用厂家能力时则经过五层:
图 4:uni-app 调用厂家设备能力的五层架构
#mermaid-svg-FlDxbyiZN9I9QyMi{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-FlDxbyiZN9I9QyMi .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-FlDxbyiZN9I9QyMi .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-FlDxbyiZN9I9QyMi .error-icon{fill:#552222;}#mermaid-svg-FlDxbyiZN9I9QyMi .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-FlDxbyiZN9I9QyMi .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-FlDxbyiZN9I9QyMi .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-FlDxbyiZN9I9QyMi .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-FlDxbyiZN9I9QyMi .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-FlDxbyiZN9I9QyMi .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-FlDxbyiZN9I9QyMi .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-FlDxbyiZN9I9QyMi .marker{fill:#333333;stroke:#333333;}#mermaid-svg-FlDxbyiZN9I9QyMi .marker.cross{stroke:#333333;}#mermaid-svg-FlDxbyiZN9I9QyMi svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-FlDxbyiZN9I9QyMi p{margin:0;}#mermaid-svg-FlDxbyiZN9I9QyMi .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-FlDxbyiZN9I9QyMi .cluster-label text{fill:#333;}#mermaid-svg-FlDxbyiZN9I9QyMi .cluster-label span{color:#333;}#mermaid-svg-FlDxbyiZN9I9QyMi .cluster-label span p{background-color:transparent;}#mermaid-svg-FlDxbyiZN9I9QyMi .label text,#mermaid-svg-FlDxbyiZN9I9QyMi span{fill:#333;color:#333;}#mermaid-svg-FlDxbyiZN9I9QyMi .node rect,#mermaid-svg-FlDxbyiZN9I9QyMi .node circle,#mermaid-svg-FlDxbyiZN9I9QyMi .node ellipse,#mermaid-svg-FlDxbyiZN9I9QyMi .node polygon,#mermaid-svg-FlDxbyiZN9I9QyMi .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-FlDxbyiZN9I9QyMi .rough-node .label text,#mermaid-svg-FlDxbyiZN9I9QyMi .node .label text,#mermaid-svg-FlDxbyiZN9I9QyMi .image-shape .label,#mermaid-svg-FlDxbyiZN9I9QyMi .icon-shape .label{text-anchor:middle;}#mermaid-svg-FlDxbyiZN9I9QyMi .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-FlDxbyiZN9I9QyMi .rough-node .label,#mermaid-svg-FlDxbyiZN9I9QyMi .node .label,#mermaid-svg-FlDxbyiZN9I9QyMi .image-shape .label,#mermaid-svg-FlDxbyiZN9I9QyMi .icon-shape .label{text-align:center;}#mermaid-svg-FlDxbyiZN9I9QyMi .node.clickable{cursor:pointer;}#mermaid-svg-FlDxbyiZN9I9QyMi .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-FlDxbyiZN9I9QyMi .arrowheadPath{fill:#333333;}#mermaid-svg-FlDxbyiZN9I9QyMi .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-FlDxbyiZN9I9QyMi .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-FlDxbyiZN9I9QyMi .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-FlDxbyiZN9I9QyMi .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-FlDxbyiZN9I9QyMi .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-FlDxbyiZN9I9QyMi .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-FlDxbyiZN9I9QyMi .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-FlDxbyiZN9I9QyMi .cluster text{fill:#333;}#mermaid-svg-FlDxbyiZN9I9QyMi .cluster span{color:#333;}#mermaid-svg-FlDxbyiZN9I9QyMi div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-FlDxbyiZN9I9QyMi .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-FlDxbyiZN9I9QyMi rect.text{fill:none;stroke-width:0;}#mermaid-svg-FlDxbyiZN9I9QyMi .icon-shape,#mermaid-svg-FlDxbyiZN9I9QyMi .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-FlDxbyiZN9I9QyMi .icon-shape p,#mermaid-svg-FlDxbyiZN9I9QyMi .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-FlDxbyiZN9I9QyMi .icon-shape .label rect,#mermaid-svg-FlDxbyiZN9I9QyMi .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-FlDxbyiZN9I9QyMi .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-FlDxbyiZN9I9QyMi .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-FlDxbyiZN9I9QyMi :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
结果或回调
标准结果
仅回调一次
稳定业务模型
Vue 页面只负责交互
services/device平台隔离、Promise、超时
UniModule参数校验、线程、生命周期
厂家 JAR/AAR设备 API
厂家系统服务/固件真实硬件行为
页面不得直接理解 AIDL、Android Context、厂家拼错的方法名或底层星期数组。 后面测试页会直接调用插件以便看清链路;正式项目必须再增加 services/device/ 封装。
3. 通用前置准备:两种打包路线都要完成
3.1 第 1 步:安装 HBuilderX
去 DCloud 官网 https://www.dcloud.io/hbuilderx.html 下载安装。装完打开,点菜单"帮助"→"关于",记录版本号,比如 5.15.2026070813。
这个版本号很重要,后面下载 Android SDK 必须和它匹配。
HBuilderX 是写 uniapp 页面的工具。版本号要记下来,因为页面资源的编译版本和 Android 运行时版本必须严格对应,不匹配运行时会出问题。
3.2 第 2 步:安装 Android Studio
去 https://developer.android.com/studio 下载安装。安装时保持默认选项。装完第一次打开会自动下载 Android SDK 组件,耐心等。
Android Studio 自带 Java 环境(JBR)。多数情况下可以直接使用,但 JDK 主版本必须满足当前 DCloud 示例工程中的 Gradle/Android Gradle Plugin 要求,不是越新越好。记住安装路径,比如 C:\\Android\\AndroidStudio,后面会用到 jbr 文件夹。
Android Studio 是写 Java 插件和打包 APK 的工具。它自带 Java,省去单独配置的麻烦。
3.3 第 3 步:下载匹配版本的 DCloud Android 离线 SDK
打开 https://nativesupport.dcloud.net.cn/AppDocs/download/android.html,找到和你 HBuilderX 版本对应的 SDK 下载。
下载后解压,里面有一个叫 UniPlugin-Hello-AS 的目录,这是 DCloud 官方给的示例工程,后面所有操作都基于它。
这个 SDK 包含 uniapp 的 Android 运行时和一个现成示例工程。版本必须和 HBuilderX 对上,否则页面资源和运行时不匹配。
开始改代码前建立版本基线,建议保存在项目记录中:
| HBuilderX | 例如 5.15.x | 帮助 → 关于 |
| DCloud Android 离线 SDK | 下载包版本 | 下载页、压缩包名、更新说明 |
| Android Studio | 实际版本 | Help → About |
| JDK/JBR | java -version | Android Studio Terminal |
| Gradle | gradlew –version | 示例工程根目录 |
| Android Gradle Plugin | 实际声明版本 | 根构建脚本或版本目录 |
| compileSdk/minSdk/targetSdk | 实际配置 | app/build.gradle |
| 目标设备 | 型号、Android、API、ABI、固件 | 设置页、ADB、厂家 Demo |
不要为了消除一个 Gradle 警告就单独升级 AGP、Gradle、AndroidX 或 DCloud AAR。先保持官方示例版本组合跑通,再评估升级。
3.4 第 4 步:收集厂家资料和设备信息
把需要的东西准备好:
- 厂家给的 JAR(本文脱敏命名为 vendor-device-sdk.jar)
- 厂家的 API 文档(告诉你 jar 里有哪些方法、参数是什么)
- 厂家的 Demo APK 或 Demo 源码
- 目标设备信息:设备型号、Android 版本、CPU 是 32 位还是 64 位
- JAR 依赖的其他 AAR/JAR/SO、AIDL、资源、License 和授权文件
- 初始化/释放方式、线程要求、回调线程和错误码说明
- Manifest 权限、系统签名、白名单、包名和证书限制
- 一台普通 Android 手机和一台厂家目标设备
jar 包是最终要调用的东西,文档告诉你怎么调,Demo 给你参考,设备信息决定打包时的兼容性配置。
把原始 SDK 放在只读资料目录,项目 libs/ 使用受控副本,并记录:文件名、版本、大小、SHA-256、来源和获取日期。厂家文档与实际 JAR 不一致时,以 可编译的实际签名 + Demo 源码 + 真机行为 为判断依据。
3.5 第 5 步:在 HBuilderX 新建项目并获取 AppID
打开 HBuilderX →"文件"→"新建"→"项目"→选"uni-app"→填项目名→选默认模板→点创建。
项目建好后,在左侧找到 manifest.json 双击打开,在“基础配置”标签页里找到 AppID,本文使用脱敏示例 __UNI__A1B2C3D。实际操作时记录自己的真实值,不要把本文示例提交到生产。
AppID 是这个应用在 DCloud 体系里的唯一身份标识,后面多处要用到,改来改去会乱套。
3.6 第 6 步:在 DCloud 后台创建证书
登录 DCloud 开发者中心 https://dev.dcloud.net.cn/:
左侧"应用管理" → 找到你的应用 → 点应用名称进入
→ 左侧"证书管理" → 点"创建证书"
选 Android 平台,点创建,等生成完成。刷新页面后点"下载",把 .keystore 文件保存到电脑上。然后点"证书详情",记录:
- 证书别名(keyAlias)
- 证书密码
- SHA-1 指纹
- SHA-256 指纹
密码属于敏感信息,不要写进代码仓库、文档、聊天记录或构建日志。 keystore 和密码需要分别备份;丢失正式私钥后,已安装应用通常无法继续覆盖升级。
证书就是给 APK 盖的"公章"。没有它打出来的包没法正式使用,换了证书就没法覆盖升级。SHA-1 指纹后面用来生成 AppKey。
3.7 第 7 步:确定 Android 包名
包名是 App 装到手机上的唯一标识,本文使用脱敏示例 com.example.classboard。正式项目应使用组织真实拥有的反向域名,不要把 com.example.* 当作生产包名。
这个包名后面会出现在三个地方,必须完全一致:
Java namespace 和源码 package 可以与 applicationId 相同以降低理解成本,但真正决定 Android 安装身份的是最终 APK 的 applicationId。
包名就是 App 在手机系统里的"户口本名字"。同包名才能覆盖升级,包名变了系统当成两个不同的 App。
3.8 第 8 步:在 DCloud 后台生成离线 AppKey
还在 DCloud 开发者中心:
左侧"各平台信息" → Android App → 选"测试版"
填三项:
| 包名 | 第 7 步定的包名 |
| 应用签名 SHA-1 | 第 6 步证书的 SHA-1 |
| 应用签名 SHA-256 | 第 6 步证书的 SHA-256 |
提交后点"查看离线 Key",生成一串 AppKey 字符串,复制保存。
AppKey 是 DCloud 发的"离线打包许可证",绑定了"AppID + 包名 + 证书 SHA-1"三者。任何一项变了,AppKey 就失效,要重新申请。
3.9 第 9 步:准备工作区外的私有签名位置
不要把正式证书直接放进可能提交 Git 的 app/ 目录。建议放入工作区外的受控目录,例如 D:/android-signing/,后面通过本机私有的 signing.properties 引用。
应用身份关系可以记成下面这张图:
图 5:AppID、包名、签名、AppKey 与覆盖升级的关系
#mermaid-svg-qfSycHQ0mkC3XZj6{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-qfSycHQ0mkC3XZj6 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-qfSycHQ0mkC3XZj6 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-qfSycHQ0mkC3XZj6 .error-icon{fill:#552222;}#mermaid-svg-qfSycHQ0mkC3XZj6 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-qfSycHQ0mkC3XZj6 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-qfSycHQ0mkC3XZj6 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-qfSycHQ0mkC3XZj6 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-qfSycHQ0mkC3XZj6 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-qfSycHQ0mkC3XZj6 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-qfSycHQ0mkC3XZj6 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-qfSycHQ0mkC3XZj6 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-qfSycHQ0mkC3XZj6 .marker.cross{stroke:#333333;}#mermaid-svg-qfSycHQ0mkC3XZj6 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-qfSycHQ0mkC3XZj6 p{margin:0;}#mermaid-svg-qfSycHQ0mkC3XZj6 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-qfSycHQ0mkC3XZj6 .cluster-label text{fill:#333;}#mermaid-svg-qfSycHQ0mkC3XZj6 .cluster-label span{color:#333;}#mermaid-svg-qfSycHQ0mkC3XZj6 .cluster-label span p{background-color:transparent;}#mermaid-svg-qfSycHQ0mkC3XZj6 .label text,#mermaid-svg-qfSycHQ0mkC3XZj6 span{fill:#333;color:#333;}#mermaid-svg-qfSycHQ0mkC3XZj6 .node rect,#mermaid-svg-qfSycHQ0mkC3XZj6 .node circle,#mermaid-svg-qfSycHQ0mkC3XZj6 .node ellipse,#mermaid-svg-qfSycHQ0mkC3XZj6 .node polygon,#mermaid-svg-qfSycHQ0mkC3XZj6 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-qfSycHQ0mkC3XZj6 .rough-node .label text,#mermaid-svg-qfSycHQ0mkC3XZj6 .node .label text,#mermaid-svg-qfSycHQ0mkC3XZj6 .image-shape .label,#mermaid-svg-qfSycHQ0mkC3XZj6 .icon-shape .label{text-anchor:middle;}#mermaid-svg-qfSycHQ0mkC3XZj6 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-qfSycHQ0mkC3XZj6 .rough-node .label,#mermaid-svg-qfSycHQ0mkC3XZj6 .node .label,#mermaid-svg-qfSycHQ0mkC3XZj6 .image-shape .label,#mermaid-svg-qfSycHQ0mkC3XZj6 .icon-shape .label{text-align:center;}#mermaid-svg-qfSycHQ0mkC3XZj6 .node.clickable{cursor:pointer;}#mermaid-svg-qfSycHQ0mkC3XZj6 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-qfSycHQ0mkC3XZj6 .arrowheadPath{fill:#333333;}#mermaid-svg-qfSycHQ0mkC3XZj6 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-qfSycHQ0mkC3XZj6 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-qfSycHQ0mkC3XZj6 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-qfSycHQ0mkC3XZj6 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-qfSycHQ0mkC3XZj6 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-qfSycHQ0mkC3XZj6 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-qfSycHQ0mkC3XZj6 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-qfSycHQ0mkC3XZj6 .cluster text{fill:#333;}#mermaid-svg-qfSycHQ0mkC3XZj6 .cluster span{color:#333;}#mermaid-svg-qfSycHQ0mkC3XZj6 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-qfSycHQ0mkC3XZj6 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-qfSycHQ0mkC3XZj6 rect.text{fill:none;stroke-width:0;}#mermaid-svg-qfSycHQ0mkC3XZj6 .icon-shape,#mermaid-svg-qfSycHQ0mkC3XZj6 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-qfSycHQ0mkC3XZj6 .icon-shape p,#mermaid-svg-qfSycHQ0mkC3XZj6 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-qfSycHQ0mkC3XZj6 .icon-shape .label rect,#mermaid-svg-qfSycHQ0mkC3XZj6 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-qfSycHQ0mkC3XZj6 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-qfSycHQ0mkC3XZj6 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-qfSycHQ0mkC3XZj6 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
uni-app AppID
DCloud 离线 AppKey
Android applicationId
签名证书 SHA-1
Android 覆盖升级身份
更大的 versionCode
Runtime 启动校验
允许覆盖安装
AppKey 校验通过与 Android 允许覆盖升级是两套相关但不同的判断。正式验收必须检查最终 APK 本身,不能只看 keystore 或后台页面。
4. 路线一:Android Studio 离线打包(推荐先走通)
适用场景:你自己一个人全包,既写前端又写 Java,Java 插件还在写、还在调。
核心特点:Java 插件以源码形式存在,Gradle 编译时直接把源码编进 APK。改 Java 代码后直接点运行就装到手机,快。
4.1 搭建 Android 宿主
第 10 步:导入示例工程
打开 Android Studio →"File"→"Open"→ 找到 UniPlugin-Hello-AS 文件夹 →"OK"。
等右下角进度条跑完(Gradle Sync),第一次可能要几分钟。完成后底部不显示红色错误就对了。
这是把官方示例工程加载进来。先跑通官方的确认环境没问题,再改成自己的。
第 11 步:跑通官方 Demo 确认环境
在 Android Studio 顶部确认运行配置选的是 app,连上手机(USB 调试 + 文件传输模式),点绿色运行按钮。如果手机能装上并打开 DCloud 示例页面,说明环境没问题。
如果 Terminal 报 JAVA_HOME is not set,执行(路径换成你的安装路径):
$env:JAVA_HOME = 'C:\\Android\\AndroidStudio\\jbr'
$env:Path = "$env:JAVA_HOME\\bin;$env:Path"
验证:
java –version
能输出版本号就行。
再记录工具链:
.\\gradlew.bat —version
adb version
如果 Android Studio 使用的 Gradle JDK 与 Terminal 的 JAVA_HOME 不同,两边可能出现“IDE 能构建、命令行不能构建”。在 Android Studio 的 Gradle 设置和 Terminal 中统一到同一个兼容 JDK。
这是"环境体检"。官方 Demo 都跑不起来,说明 SDK、Java 或 Gradle 有问题,先解决再往下走。
第 12 步:复制一份作为项目专用宿主
关掉 Android Studio。把 UniPlugin-Hello-AS 文件夹复制一份,本文将副本命名为 ClassBoardDemo-Android。然后删掉这些缓存:
ClassBoardDemo-Android/.gradle/
ClassBoardDemo-Android/.idea/
ClassBoardDemo-Android/.kotlin/
ClassBoardDemo-Android/local.properties
ClassBoardDemo-Android/app/build/
这些是本机缓存或构建产物,复制后可以重新生成。官方那份留着不动,出问题时用来对比。删除前先确认路径确实位于新复制的项目宿主内,不要误删原始 SDK。
删完后用 Android Studio 重新打开 ClassBoardDemo-Android,等 Gradle Sync 完成。
这是"分家"。官方工程当参照物,你自己的项目在副本上改,互不干扰。
第 13 步:配置 local.properties
打开工程根目录的 local.properties(没有就新建),写 Android SDK 路径:
sdk.dir=C\\:\\\\Users\\\\你的用户名\\\\AppData\\\\Local\\\\Android\\\\Sdk
不知道路径?Android Studio →"File"→"Settings"→"Languages & Frameworks"→"Android SDK",里面的"Android SDK Location"就是。
这个文件告诉 Gradle 你的 Android SDK 装在哪。每台电脑不一样,不能提交到代码仓库。
第 14 步:配置 app/build.gradle
把文件视图从"Android"切换成"Project"。打开 app/build.gradle,修改 defaultConfig:
android {
namespace 'com.example.classboard'
defaultConfig {
applicationId "com.example.classboard"
minSdkVersion 21
targetSdkVersion 32
versionCode 100
versionName "1.0.0"
multiDexEnabled true
}
}
- applicationId:第 7 步定的包名
- versionCode:整数,每次升级必须递增
- versionName:给人看的版本号
在宿主根目录创建只保存在本机的 signing.properties:
storeFile=D:/android-signing/myapp.keystore
storePassword=仅在本机填写
keyAlias=正式证书别名
keyPassword=仅在本机填写
.gitignore 至少加入:
signing.properties
*.keystore
*.jks
local.properties
.gradle/
.idea/
.kotlin/
**/build/
在 app/build.gradle 顶部读取私有配置:
def signingProperties = new Properties()
def signingPropertiesFile = rootProject.file('signing.properties')
def hasSigningProperties = signingPropertiesFile.exists()
if (hasSigningProperties) {
signingPropertiesFile.withInputStream { signingProperties.load(it) }
}
def requiredSigningKeys = ['storeFile', 'storePassword', 'keyAlias', 'keyPassword']
def signingReady = hasSigningProperties && requiredSigningKeys.every {
signingProperties[it]?.trim()
}
def requestedRelease = gradle.startParameter.taskNames.any {
it.toLowerCase().contains('release')
}
if (requestedRelease && !signingReady) {
throw new GradleException('Release 构建缺少完整的本机签名配置')
}
然后在 android {} 内配置签名:
signingConfigs {
if (signingReady) {
formal {
storeFile file(signingProperties['storeFile'])
storePassword signingProperties['storePassword']
keyAlias signingProperties['keyAlias']
keyPassword signingProperties['keyPassword']
// Android 7 以下设备需要 V1;现代设备同时保留 V2。
v1SigningEnabled true
v2SigningEnabled true
}
}
}
buildTypes {
release {
if (signingReady) {
signingConfig signingConfigs.formal
}
}
}
改完点"Sync Now"。
默认 Debug 包使用 Android Debug 证书,只适合快速编译和桥接调试;正式 AppKey、覆盖升级和交付必须用正式签名的 APK 验证。确实需要 Debug 也使用正式签名时可以显式配置,但要理解这会扩大正式私钥的使用范围。
第 15 步:验证签名配置
Terminal 执行(确认 JAVA_HOME 设好了):
.\\gradlew.bat :app:signingReport
找到 release 变体使用的证书,核对 SHA-1 是否和 DCloud 后台一致。BUILD SUCCESSFUL 只说明报告生成成功,不代表最终 APK 一定已正确签名;后文“APK 构建后的静态校验”还会检查 APK 本身。
SHA-1 必须和 DCloud 后台完全一致——不一致说明签名配置没生效,后面 AppKey 会校验失败。
第 16 步:配置 AndroidManifest.xml 的 AppKey
打开 app/src/main/AndroidManifest.xml,在 <application> 结束标签之前加入:
<meta-data
android:name="dcloud_appkey"
android:value="第8步生成的AppKey" />
如果已经有 dcloud_appkey,把 value 改成你的,不要重复加。
AppKey 是 DCloud 给你的"营业执照",APK 启动时 DCloud 运行时读这个值验证。
第 17 步:配置 dcloud_control.xml
打开 app/src/main/assets/data/dcloud_control.xml:
<hbuilder>
<apps>
<app appid="__UNI__A1B2C3D" appver="" />
</apps>
</hbuilder>
AppID 必须和你的 uniapp 项目一致(第 5 步记的那个)。
这个文件决定宿主启动加载哪个 AppID 的页面。写错了要么白屏要么加载到旧页面。
4.2 创建原生插件 Module
第 18 步:新建 Android Library Module
“File"→"New"→"New Module"→选"Android Library"→"Next”。填写:
| Module name | demo_device |
| Package name | com.example.device |
| Language | Java |
| Minimum SDK | API 21 |
| Build Configuration Language | Groovy DSL |
点 Finish。左侧项目树多了一个 demo_device 目录。
这是创建独立的"插件模块"。它是一个 Android Library,专门写对接 jar 包的 Java 代码,和宿主分开管理。
第 19 步:配置 Module 的 build.gradle
打开 demo_device/build.gradle,按当前官方示例调整 dependencies:
repositories {
flatDir {
dirs 'libs'
}
}
dependencies {
// 文件名以当前 DCloud 官方示例工程为准。
// DCloud 核心 AAR 只参与编译,由宿主提供,避免重复类。
compileOnly fileTree(
dir: '../app/libs',
include: ['uniapp-v8-release.aar']
)
compileOnly 'androidx.recyclerview:recyclerview:1.0.0'
compileOnly 'androidx.legacy:legacy-support-v4:1.0.0'
compileOnly 'androidx.appcompat:appcompat:1.0.0'
// fastjson 用 implementation,真正进 APK
implementation 'com.alibaba:fastjson:1.2.83'
// 仅在保留 Android Studio 自动生成的测试源码时需要。
testImplementation 'junit:junit:4.13.2'
androidTestImplementation 'androidx.test.ext:junit:1.1.5'
androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
}
点"Sync Now"。
DCloud AAR 用 compileOnly:编译时需要认识这些类,但由宿主提供运行时实现。Fastjson 是否需要 implementation 取决于当前 DCloud SDK 和你的插件是否已提供兼容版本;先检查官方示例和依赖树,不要无条件再打包一份。若删除自动生成的 src/test 与 src/androidTest,三条测试依赖也可以不加。
查看依赖归属:
.\\gradlew.bat :app:dependencies —configuration debugRuntimeClasspath
目标是每个运行时类只有一个提供者:
图 6:AAR/JAR 依赖归属决策
#mermaid-svg-34UKHnNqXzLbl1a8{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-34UKHnNqXzLbl1a8 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-34UKHnNqXzLbl1a8 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-34UKHnNqXzLbl1a8 .error-icon{fill:#552222;}#mermaid-svg-34UKHnNqXzLbl1a8 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-34UKHnNqXzLbl1a8 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-34UKHnNqXzLbl1a8 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-34UKHnNqXzLbl1a8 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-34UKHnNqXzLbl1a8 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-34UKHnNqXzLbl1a8 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-34UKHnNqXzLbl1a8 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-34UKHnNqXzLbl1a8 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-34UKHnNqXzLbl1a8 .marker.cross{stroke:#333333;}#mermaid-svg-34UKHnNqXzLbl1a8 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-34UKHnNqXzLbl1a8 p{margin:0;}#mermaid-svg-34UKHnNqXzLbl1a8 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-34UKHnNqXzLbl1a8 .cluster-label text{fill:#333;}#mermaid-svg-34UKHnNqXzLbl1a8 .cluster-label span{color:#333;}#mermaid-svg-34UKHnNqXzLbl1a8 .cluster-label span p{background-color:transparent;}#mermaid-svg-34UKHnNqXzLbl1a8 .label text,#mermaid-svg-34UKHnNqXzLbl1a8 span{fill:#333;color:#333;}#mermaid-svg-34UKHnNqXzLbl1a8 .node rect,#mermaid-svg-34UKHnNqXzLbl1a8 .node circle,#mermaid-svg-34UKHnNqXzLbl1a8 .node ellipse,#mermaid-svg-34UKHnNqXzLbl1a8 .node polygon,#mermaid-svg-34UKHnNqXzLbl1a8 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-34UKHnNqXzLbl1a8 .rough-node .label text,#mermaid-svg-34UKHnNqXzLbl1a8 .node .label text,#mermaid-svg-34UKHnNqXzLbl1a8 .image-shape .label,#mermaid-svg-34UKHnNqXzLbl1a8 .icon-shape .label{text-anchor:middle;}#mermaid-svg-34UKHnNqXzLbl1a8 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-34UKHnNqXzLbl1a8 .rough-node .label,#mermaid-svg-34UKHnNqXzLbl1a8 .node .label,#mermaid-svg-34UKHnNqXzLbl1a8 .image-shape .label,#mermaid-svg-34UKHnNqXzLbl1a8 .icon-shape .label{text-align:center;}#mermaid-svg-34UKHnNqXzLbl1a8 .node.clickable{cursor:pointer;}#mermaid-svg-34UKHnNqXzLbl1a8 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-34UKHnNqXzLbl1a8 .arrowheadPath{fill:#333333;}#mermaid-svg-34UKHnNqXzLbl1a8 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-34UKHnNqXzLbl1a8 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-34UKHnNqXzLbl1a8 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-34UKHnNqXzLbl1a8 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-34UKHnNqXzLbl1a8 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-34UKHnNqXzLbl1a8 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-34UKHnNqXzLbl1a8 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-34UKHnNqXzLbl1a8 .cluster text{fill:#333;}#mermaid-svg-34UKHnNqXzLbl1a8 .cluster span{color:#333;}#mermaid-svg-34UKHnNqXzLbl1a8 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-34UKHnNqXzLbl1a8 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-34UKHnNqXzLbl1a8 rect.text{fill:none;stroke-width:0;}#mermaid-svg-34UKHnNqXzLbl1a8 .icon-shape,#mermaid-svg-34UKHnNqXzLbl1a8 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-34UKHnNqXzLbl1a8 .icon-shape p,#mermaid-svg-34UKHnNqXzLbl1a8 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-34UKHnNqXzLbl1a8 .icon-shape .label rect,#mermaid-svg-34UKHnNqXzLbl1a8 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-34UKHnNqXzLbl1a8 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-34UKHnNqXzLbl1a8 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-34UKHnNqXzLbl1a8 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
DCloud 宿主已经有
插件独占且需进 APK
厂家 JAR 已嵌入 AAR
厂家 JAR 独立交付
这个依赖由谁提供?
插件 compileOnly
implementation 或插件目录 libs
插件目录不要再放同一 JAR
AAR 不内嵌,放 android/libs 一份
检查最终 APK
第 20 步:配置混淆文件
Library 自己的 proguard-rules.pro 不一定会自动传递给最终 App。更稳妥的做法是在 demo_device/build.gradle 中声明消费者规则:
android {
defaultConfig {
consumerProguardFiles 'consumer-rules.pro'
}
}
在 demo_device/consumer-rules.pro 中加入:
-keep public class * extends io.dcloud.feature.uniapp.common.UniModule { public *; }
厂家 SDK 如果通过反射、JNI 或固定类名访问,还要合并厂家提供的 keep 规则。只有在 minifyEnabled true 时 R8/混淆才真正参与;无论是否开启,都要对 Release 产物验证插件调用。
第 21 步:写最小 sayHi 方法
展开 demo_device → src → main → java → com.example.device,右键包 → “New” → “Java Class”,类名填 DemoDeviceModule。内容:
package com.example.device;
import com.alibaba.fastjson.JSONObject;
import io.dcloud.feature.uniapp.annotation.UniJSMethod;
import io.dcloud.feature.uniapp.bridge.UniJSCallback;
import io.dcloud.feature.uniapp.common.UniModule;
public class DemoDeviceModule extends UniModule {
/**
* 验证 JavaScript 到原生 Module 的最小桥接。
*
* @param name 用于回显的名称;null 时按空字符串处理
* @param callback 返回统一结果;callback 为空时不执行回调
*/
@UniJSMethod(uiThread = true)
public void sayHi(String name, UniJSCallback callback) {
if (callback == null) {
return;
}
JSONObject result = new JSONObject();
result.put("success", true);
result.put("code", "SUCCESS");
result.put("message", "你好," + (name == null ? "" : name));
result.put("data", new JSONObject());
callback.invoke(result);
}
}
两条硬性规则:
- @UniJSMethod(uiThread = true) 注解必须加,否则前端调不到
- 方法必须是 public,因为 uniapp 通过 Java 反射调用
这是写最简单的方法验证桥接链路。先不碰 jar 包,排除两类问题同时排查的混乱。
第 22 步:注册插件到 dcloud_uniplugins.json
打开 app/src/main/assets/dcloud_uniplugins.json,在 nativePlugins 数组里加:
{
"nativePlugins": [
{
"type": "module",
"name": "DemoDevicePlugin",
"class": "com.example.device.DemoDeviceModule"
}
]
}
注意 JSON 语法,项之间用逗号,最后一项后面不要逗号。
这是“登记造册”,让 DCloud Runtime 知道 requireNativePlugin('DemoDevicePlugin') 对应哪个 Java 类。
第 23 步:让宿主引用你的 Module
打开 app/build.gradle,在 dependencies 加:
implementation project(':demo_device')
打开根目录 settings.gradle,确认有:
include ':demo_device'
点"Sync Now"。
这步让宿主工程知道"我依赖这个插件模块"。不声明,宿主编译时不会把你的插件代码打包进 APK。
第 24 步:编译验证
.\\gradlew.bat :demo_device:assembleDebug
BUILD SUCCESSFUL 说明 Module 本身没问题。如果报 程序包 org.junit 不存在,回第 19 步检查测试依赖那三行。
再编译整个宿主:
.\\gradlew.bat :app:assembleDebug
BUILD SUCCESSFUL 说明你的 Module 已正确进入编译链路。
分层编译验证:先确认插件本身没问题,再确认宿主打包没问题。出了问题好定位是插件的问题还是宿主的问题。
4.3 打通 JavaScript 到 Java 的最小调用链
第 25 步:在 HBuilderX 写测试页面
<template>
<view style="padding: 20px;">
<button type="primary" @click="testSayHi">测试原生插件</button>
<view style="margin-top: 20px; padding: 15px; background: #f5f5f5; border-radius: 8px;">
<text>{{ result }}</text>
</view>
</view>
</template>
<script>
let plugin = null
// #ifdef APP-PLUS
plugin = uni.requireNativePlugin('DemoDevicePlugin')
// #endif
export default {
data() {
return {
result: '点击按钮测试'
}
},
methods: {
testSayHi() {
if (!plugin) {
this.result = '当前平台不支持 Android 原生插件'
return
}
plugin.sayHi('示例班牌', (res) => {
this.result = res.message
uni.showToast({
title: res.message,
icon: 'none',
duration: 2
})
})
}
}
}
</script>
uni.requireNativePlugin('DemoDevicePlugin') 里的名字必须和第 22 步 dcloud_uniplugins.json 里注册的 name 完全一致。条件编译用于避免非 App-Plus 构建误用 Android 插件,但 H5 返回“不支持”不能当作原生能力测试通过。
这是写前端页面。名字对不上就调不到,这是最常见的错误。
第 26 步:生成本地打包资源
HBuilderX →"发行"→"原生App-本地打包"→"生成本地打包App资源"。
等编译完成,输出路径类似:
你的uniapp项目/unpackage/resources/__UNI__A1B2C3D/www
这一步只生成 www 文件夹,不是 APK。
这里执行的是“本地打包资源”,所以只生成 www。若选择“原生 App-云打包”,HBuilderX 会把任务提交到云端并生成 APK。
第 27 步:复制资源到 Android 宿主
把 __UNI__A1B2C3D 整个文件夹复制到:
ClassBoardDemo-Android/app/src/main/assets/apps/
最终目录结构:
app/src/main/assets/
├─ apps/
│ └─ __UNI__A1B2C3D/
│ └─ www/
└─ data/
└─ dcloud_control.xml
三个必须检查的点:
这是"搬家"。搬错路径或 AppID 对不上,宿主启动时找不到页面就白屏。仔细检查目录结构。
第 28 步:构建 Debug APK
.\\gradlew.bat :app:assembleDebug
APK 在 app/build/outputs/apk/debug/app-debug.apk。
这是"第二次构建",把前端资源和原生插件组装成 APK。每次改了前端页面都要重新走"生成资源→复制→构建"这个循环。
第 29 步:连接手机并运行
手机开启"开发者选项"→"USB 调试",连上 USB 后选"文件传输"模式(不是"仅充电")。
Android Studio 顶部确认运行配置是 app,设备下拉框显示你的手机型号。点绿色运行按钮。
手机虽然开了 USB 调试,但如果 USB 用途是"仅充电",电脑看不到手机。必须切到"文件传输"。
第 30 步:验证 sayHi
App 启动后进入测试页面,点按钮。如果弹出 Toast 显示 你好,示例班牌,最小调用链打通了。
如果没反应,检查:
- requireNativePlugin 名字和 dcloud_uniplugins.json 里 name 是否一致
- Java 方法的 @UniJSMethod 注解是否加了
- 方法是否 public
- 第 27 步 www 是不是最新复制过去的
这步证明从前端到 Java 再到回调的整条桥接链路没问题。链路通了,后面接 jar 包就只是加 Java 代码。
4.4 引入厂家 JAR
第 31 步:把 jar 包放到 libs 目录
把受控的厂家 JAR 副本复制到 ClassBoardDemo-Android/demo_device/libs/(没有 libs 就新建)。用 SHA-256 核对,并把结果写入不公开的项目记录:
Get-FileHash demo_device/libs/vendor-device-sdk.jar –Algorithm SHA256
核对哈希是为了确认文件复制完整没损坏。
第 32 步:用 javap 查看方法签名
javap –classpath demo_device/libs/vendor-device-sdk.jar com.vendor.device.DeviceManager
com.vendor.device.DeviceManager 是脱敏占位名,必须换成实际管理类全名。输出可能类似:
public static synchronized DeviceManager getInstance(android.content.Context);
public String getApiVersion();
public String getDeviceModel();
public String getSystemVersion();
把方法名和参数类型都记下来。 写 Java 代码时必须严格按这个签名调,一个字母都不能改。如果厂家拼错了,你也用拼错的。
这是"摸清 jar 包的接口"。不看签名直接写代码,方法名拼错就编译不过;参数类型搞错就运行时崩。厂家文档和实际 jar 包可能有出入,以 jar 实际签名为准。
第 33 步:明确厂家 JAR 的编译期和运行时归属
脱敏项目采用“薄 AAR + 独立厂家 JAR”,因此 Module 只在编译期引用 JAR。打开 demo_device/build.gradle:
// Module 编译时识别厂家类,但不把 JAR 嵌入 AAR。
compileOnly files('libs/vendor-device-sdk.jar')
再由路线一的 app/build.gradle 提供唯一运行时副本:
dependencies {
implementation project(':demo_device')
implementation files('../demo_device/libs/vendor-device-sdk.jar')
}
路线二则由 nativeplugins/DemoDevicePlugin/android/libs/vendor-device-sdk.jar 提供同一运行时副本。这样 Module 生成的 AAR始终不内嵌厂家 JAR,便于两条路线复用。
点"Sync Now"。
compileOnly 本身没有问题,问题是最终 APK 必须另有且只有一个运行时提供者。若选择自包含 AAR,就改用经过验证的内嵌方案,并删除宿主/插件目录中的独立 JAR;两种策略不能混用。
第 34 步:写 getDeviceInfo 只读方法
package com.example.device;
import com.alibaba.fastjson.JSONObject;
import com.vendor.device.DeviceManager;
import io.dcloud.feature.uniapp.annotation.UniJSMethod;
import io.dcloud.feature.uniapp.bridge.UniJSCallback;
import io.dcloud.feature.uniapp.common.UniModule;
import android.content.Context;
import android.util.Log;
public class DemoDeviceModule extends UniModule {
private static final String TAG = "DemoDevicePlugin";
private DeviceManager manager = null;
private synchronized DeviceManager getOrCreateManager() {
if (manager == null) {
Context context = mUniSDKInstance.getContext().getApplicationContext();
manager = DeviceManager.getInstance(context);
}
return manager;
}
/**
* 验证 JavaScript 到原生 Module 的桥接,不调用厂家 SDK。
*
* @param name 回显名称;null 时按空字符串处理
* @param callback 返回 success/code/message/data;为空时不回调
*/
@UniJSMethod(uiThread = true)
public void sayHi(String name, UniJSCallback callback) {
if (callback == null) return;
JSONObject result = new JSONObject();
result.put("success", true);
result.put("code", "SUCCESS");
result.put("message", "你好," + (name == null ? "" : name));
result.put("data", new JSONObject());
callback.invoke(result);
}
/**
* 读取无副作用的设备信息。
*
* @param callback 成功时 data 为稳定字段;SDK 缺失或调用异常时返回可区分错误码
*/
@UniJSMethod(uiThread = true)
public void getDeviceInfo(UniJSCallback callback) {
if (callback == null) return;
JSONObject result = new JSONObject();
try {
DeviceManager mgr = getOrCreateManager();
JSONObject data = new JSONObject();
data.put("apiVersion", mgr.getApiVersion());
data.put("model", mgr.getDeviceModel());
data.put("androidVersion", mgr.getSystemVersion());
data.put("firmwareVersion", mgr.getFirmwareVersion());
data.put("firmwareBuild", mgr.getBuildDisplay());
data.put("firmwareDate", mgr.getFirmwareDate());
data.put("cpuType", mgr.getCpuType());
result.put("success", true);
result.put("code", "SUCCESS");
result.put("message", "设备信息方法调用成功");
result.put("data", data);
callback.invoke(result);
} catch (RuntimeException e) {
Log.e(TAG, "SDK调用失败", e);
result.put("success", false);
result.put("code", "SDK_CALL_FAILED");
result.put("message", "厂家SDK调用异常");
callback.invoke(result);
} catch (LinkageError e) {
Log.e(TAG, "SDK链接错误", e);
result.put("success", false);
result.put("code", "SDK_LINK_ERROR");
result.put("message", "厂家SDK版本不兼容");
callback.invoke(result);
}
}
}
几个要点:
- 这里的方法名和 DeviceManager 都是脱敏占位,必须按实际 JAR 修改。
- getOrCreateManager() 使用 Application Context,避免长期持有 Activity。
- 示例只调用不依赖 AIDL 的只读方法,不在尚未连接成功时抢跑系统服务调用。
- 异常分为 SDK 运行异常和链接/版本不兼容,页面不显示底层堆栈。
- 每个分支只执行一次回调,返回结构统一用 success/code/message/data。
先只做只读方法,没有副作用,调错了也不会把设备搞坏。等只读链路稳定了,再逐步加写入和控制能力。
AIDL / Service 生命周期不能照抄一行绑定
脱敏项目实测确认:部分厂家能力依赖跨进程服务,但“调用了 bind”不等于“服务已经可用”。正确流程应是:
图 7:AIDL/Service 连接状态机
#mermaid-svg-KFV7edoky66H0zJ8{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-KFV7edoky66H0zJ8 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-KFV7edoky66H0zJ8 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-KFV7edoky66H0zJ8 .error-icon{fill:#552222;}#mermaid-svg-KFV7edoky66H0zJ8 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-KFV7edoky66H0zJ8 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-KFV7edoky66H0zJ8 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-KFV7edoky66H0zJ8 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-KFV7edoky66H0zJ8 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-KFV7edoky66H0zJ8 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-KFV7edoky66H0zJ8 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-KFV7edoky66H0zJ8 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-KFV7edoky66H0zJ8 .marker.cross{stroke:#333333;}#mermaid-svg-KFV7edoky66H0zJ8 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-KFV7edoky66H0zJ8 p{margin:0;}#mermaid-svg-KFV7edoky66H0zJ8 defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-KFV7edoky66H0zJ8 g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-KFV7edoky66H0zJ8 g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-KFV7edoky66H0zJ8 g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-KFV7edoky66H0zJ8 g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-KFV7edoky66H0zJ8 g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-KFV7edoky66H0zJ8 .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-KFV7edoky66H0zJ8 .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-KFV7edoky66H0zJ8 .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-KFV7edoky66H0zJ8 .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-KFV7edoky66H0zJ8 .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-KFV7edoky66H0zJ8 .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-KFV7edoky66H0zJ8 .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-KFV7edoky66H0zJ8 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-KFV7edoky66H0zJ8 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-KFV7edoky66H0zJ8 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-KFV7edoky66H0zJ8 .edgeLabel .label text{fill:#333;}#mermaid-svg-KFV7edoky66H0zJ8 .label div .edgeLabel{color:#333;}#mermaid-svg-KFV7edoky66H0zJ8 .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-KFV7edoky66H0zJ8 .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-KFV7edoky66H0zJ8 .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-KFV7edoky66H0zJ8 .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-KFV7edoky66H0zJ8 .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-KFV7edoky66H0zJ8 .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-KFV7edoky66H0zJ8 .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-KFV7edoky66H0zJ8 #statediagram-barbEnd{fill:#333333;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-KFV7edoky66H0zJ8 .cluster-label,#mermaid-svg-KFV7edoky66H0zJ8 .nodeLabel{color:#131300;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-KFV7edoky66H0zJ8 .note-edge{stroke-dasharray:5;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-note text{fill:black;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram-note .nodeLabel{color:black;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagram .edgeLabel{color:red;}#mermaid-svg-KFV7edoky66H0zJ8 #dependencyStart,#mermaid-svg-KFV7edoky66H0zJ8 #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-KFV7edoky66H0zJ8 .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-KFV7edoky66H0zJ8 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
首次需要服务能力
onServiceConnected
超时或绑定失败
后续调用复用连接
binderDied/onServiceDisconnected
有限次数重连
App/Module 最终释放
明确重试
Unbound
Binding
Ready
Failed
Disconnected
实现时必须根据实际 SDK 回答四个问题:
如果厂家 API 没有就绪回调,插件层要使用有上限的状态检查或明确返回 SERVICE_NOT_READY,不能在 Vue 页面里用固定 setTimeout 猜服务已经连接。解绑只能在与实际持有者匹配的最终生命周期执行,不能把“页面销毁”简单等同于“整个 App 不再需要服务”。
第 35 步:编译验证
.\\gradlew.bat :demo_device:assembleDebug
.\\gradlew.bat :app:assembleDebug
第 36 步:验证 jar 包进了 APK
apkanalyzer dex packages app\\build\\outputs\\apk\\debug\\app-debug.apk | findstr "com.vendor.device.DeviceManager"
确认 DeviceManager 定义数量为 1:
- 0 → JAR 没进入 APK,检查宿主或本地插件是否提供了运行时副本
-
1 → 重复打包了,检查是不是多处放了同一份 jar
“编译成功”不等于“JAR 进了 APK”。apkanalyzer、反编译结果和运行时加载要结合判断;工具命令随 Android SDK 版本可能略有不同。
第 37 步:前端加 getDeviceInfo 按钮
<template>
<view style="padding: 20px;">
<button type="primary" @click="testSayHi">测试原生插件</button>
<button type="primary" @click="testGetDeviceInfo" style="margin-top: 10px;">读取设备信息</button>
<scroll-view scrollY style="margin-top: 20px; padding: 15px; background: #f5f5f5; border-radius: 8px; max-height: 400px;">
<text>{{ result }}</text>
</scroll-view>
</view>
</template>
<script>
let plugin = null
// #ifdef APP-PLUS
plugin = uni.requireNativePlugin('DemoDevicePlugin')
// #endif
export default {
data() {
return { result: '点击按钮测试' }
},
methods: {
testSayHi() {
if (!plugin) {
this.result = '当前平台不支持 Android 原生插件'
return
}
plugin.sayHi('示例班牌', (res) => {
this.result = res.message
uni.showToast({ title: res.message, icon: 'none', duration: 2 })
})
},
testGetDeviceInfo() {
if (!plugin) {
this.result = '当前平台不支持 Android 原生插件'
return
}
plugin.getDeviceInfo((res) => {
if (res.success) {
this.result = JSON.stringify(res.data, null, 2)
} else {
this.result = '错误: ' + res.code + ' – ' + res.message
}
})
}
}
}
</script>
第 38 步:重新生成资源 + 复制 + 构建
每次改前端页面都做这三步:
改完页面没重新生成+复制,Android 打出来的还是旧页面。
第 39 步:普通手机验证
点运行按钮装到手机,点"读取设备信息"。
普通手机上方法可能返回数据(手机品牌、系统版本等),但这只证明 jar 包能加载、方法能调用。普通手机没有厂家固件,厂家专属字段可能是空的或默认值,正常。
普通手机验证的是"桥接和调用链路"是否通畅,不是"厂家设备能力"是否可用。真正能力必须目标设备验证。
4.5 在目标设备上完成真机验证
第 40 步:准备 U 盘安装包
U 盘根目录创建全英文文件夹(如 classboard_test),把 app-debug.apk 复制进去,文件名用纯英文(如 test.apk)。核对 SHA-256。
中文路径可能导致旧版 Android 文件管理器出问题。全英文路径是低成本排除项。
第 41 步:检查 APK 和目标设备兼容性
aapt.exe dump badging app-debug.apk
核对:
- sdkVersion 不高于目标设备 API Level
- native-code 包含目标设备 CPU 架构
脱敏项目实测设备是 32 位 ARMv7,因此需要 armeabi-v7a。曾有云端基座只包含 arm64-v8a,旧系统只显示笼统的“应用未安装”,ADB 实际会给出 INSTALL_FAILED_NO_MATCHING_ABIS。这个结论说明必须验 APK 的真实 ABI,不能照抄到其他型号。
这是"兼容性体检"。最低系统版本和 CPU 架构是硬门槛,不满足连装都装不上。
第 42 步:在目标设备上安装和验证
U 盘插到目标设备,文件管理器点击安装。打开 App:
在脱敏目标设备上可能返回类似:
model: VendorBoard-A
firmwareVersion: 1.0
apiVersion: 2023-11-23
firmwareDate: 20230217
androidVersion: 22
cpuType: ARMv7 Processor rev 1 (v7l)
到这里,从前端到 jar 包到硬件的完整调用链打通了。
这是目标设备验收。普通手机只能验证桥接链路,厂家设备才能验证固件能力。普通手机能返回数据但目标设备失败时,问题通常位于固件、权限或 AIDL 服务层。
4.6 路线一的日常开发循环
Java 插件稳定后,你日常就是改前端。每次改完走这个循环:
HBuilderX 改前端 → 生成资源 → 复制到工程 → Gradle 编译 → 出 APK
只在 Android Studio 改 Java 代码时,直接跑 Gradle 编译就行,不用回 HBuilderX。
5. 路线二:本地原生插件、自定义基座与云打包
适用场景:
- Java 插件已经写好调通,以后只改前端
- 你只写前端,Java 插件是别人给你 AAR
- 不想每次改前端都开 Android Studio
核心特点:插件先编译成 AAR,放到 uni-app 项目的 nativeplugins,再由 HBuilderX 制作自定义基座或云打包 APK。只负责消费已稳定 AAR 的前端开发者可以不打开 Android Studio;负责修改 Java、生成或排查 AAR 的开发者仍然需要 Android Studio/Gradle 工具链。
5.1 切换云打包前的条件
切到云打包之前确认:
- 插件 Module 已经在 Android Studio 里写好、编译通过
- 厂家 JAR 的归属已经确定;本文使用“薄 AAR + 插件目录独立 JAR”
- 插件已经在 dcloud_uniplugins.json 里注册过
- 最好已经在真机上用路线一验证过功能正常
先用路线一跑通、验证 Java 插件没问题,再切路线二。因为路线二改 Java 后要重新打 AAR、重新打基座,慢且不好调试。
5.2 编译插件 AAR
云打包第 1 步:编译 AAR
打开 Android Studio Terminal:
.\\gradlew.bat :demo_device:assembleRelease
找不到 other 目录的 assembleRelease? 新版 AS 默认不显示 Tasks 列表,去 File → Settings → Experimental → 取消"Do not build Gradle task list during Gradle sync",重新 Sync。
成功后 AAR 在:
demo_device/build/outputs/aar/demo_device-release.aar
这是把插件 Java 代码编译成 AAR。本文采用薄 AAR,因此厂家 JAR 不进入 AAR,而是在本地插件目录中单独提供。
云打包第 2 步:检查 AAR 与厂家 JAR 归属
把 AAR 当作 ZIP 查看,至少检查 classes.jar、Manifest、资源和 libs/。厂家依赖只能选择一种交付策略:
| 薄 AAR,本文采用 | 不含厂家 JAR | 放一份厂家 JAR | 便于单独核对厂家原件和哈希 |
| 自包含 AAR | 明确包含厂家类 | 不再放相同 JAR | 便于交付单个 AAR,但必须确认构建确实内嵌 |
脱敏项目实测采用第一种:AAR 中没有厂家 JAR,android/libs/vendor-device-sdk.jar 是厂家类的唯一来源。不要同时放两份,也不要只凭 Gradle 声明猜测产物内容。
5.3 配置 uni-app 本地插件目录
云打包第 3 步:创建插件目录
在 uniapp 项目根目录创建:
你的uniapp项目/
└─ nativeplugins/
└─ DemoDevicePlugin/
├─ package.json
└─ android/
├─ demo_device-release.aar
└─ libs/
└─ vendor-device-sdk.jar
把 AAR 放到 android/,厂家 JAR 放到 android/libs/。package.json 位于插件 ID 根目录,不能放进 android/。
云打包第 4 步:创建 package.json
在 nativeplugins/DemoDevicePlugin/ 下新建 package.json:
{
"name": "示例设备能力插件",
"id": "DemoDevicePlugin",
"version": "1.0.0",
"description": "示例班牌 Android 设备能力插件",
"_dp_type": "nativeplugin",
"_dp_nativeplugin": {
"android": {
"plugins": [
{
"type": "module",
"name": "DemoDevicePlugin",
"class": "com.example.device.DemoDeviceModule"
}
],
"integrateType": "aar",
"parameters": {},
"dependencies": [
"com.alibaba:fastjson:1.2.83"
],
"minSdkVersion": "21",
"permissions": []
}
}
}
几个必须对上的:
| id | 插件目录名和本地插件唯一 ID |
| plugins[0].name | 前端 requireNativePlugin() 的调用名 |
| plugins[0].class | Java 类的完整包名+类名 |
顶层 name 是展示名称,可以写可读中文;真正需要严格对应的是目录 ID、id、plugins[0].name 和前端调用名。dependencies 只写 Maven 坐标,普通 JAR/SO 通过插件目录交付,不把文件名写成 Maven 依赖。
package.json 必须是严格 JSON,不能写注释,最后一个属性后面不能有逗号。
云打包第 5 步:在 manifest.json 引入插件
打开 manifest.json,切换到“App 原生插件配置”,勾选 DemoDevicePlugin。
优先用 HBuilderX 可视化界面生成配置。当前版本的源码结构通常是 app-plus.nativePlugins 对象,脱敏示例如下;不同 HBuilderX 版本生成的元数据可能不同,不要把旧教程中的数组结构强行覆盖进去:
"nativePlugins": {
"DemoDevicePlugin": {
"__plugin_info__": {
"name": "示例设备能力插件",
"description": "Android 设备能力教学示例",
"platforms": "Android"
}
}
}
5.4 制作自定义调试基座
云打包第 6 步:打自定义调试基座
云打包用的是 DCloud 的标准基座,里面没有你的插件,所以要先打一个"自定义基座"——带了你插件的调试包。
HBuilderX → 运行 → 运行到手机或模拟器 → 制作自定义调试基座
填入包名、证书,点打包。等云打包完成。
自定义基座相当于"带了调料的盘子",装到手机后你改前端代码可以直接热刷新到这个基座里调试。
云打包第 7 步:运行自定义基座
运行 → 运行到手机或模拟器 → 运行基座选择 → 自定义调试基座
选好后点运行,HBuilderX 把基座装到手机并推送前端代码。
5.5 验证插件并执行正式云打包
云打包第 8 步:验证功能
手机上打开 App,测试 sayHi 和 getDeviceInfo 是否正常。
云打包第 9 步:正式云打包出 APK
HBuilderX → 发行 → 原生App-云打包
勾选 Android,选择正式证书,确认启用了 DemoDevicePlugin,再提交打包。下载 APK 后仍要执行签名、ABI、插件类和真机检查。
5.6 路线二的日常开发循环
Java 插件稳定后,路线二日常就是改前端:
HBuilderX 改前端 → 发行 → 云打包 → 下载 APK
不用碰 Android Studio,不用手动复制资源,不用跑 Gradle。
5.7 云打包常见问题
云打包提示"不包含插件":检查 package.json 路径、AAR 文件位置、manifest.json 是否勾选。
插件方法调不到:检查 package.json 里 class 路径和 Java 类实际路径是否完全一致。
jar 包冲突:AAR 里有 jar 包,同时 dependencies 又声明了相同 Maven 依赖,会报 Duplicate class。两者只保留一个。
改了 Java 代码忘了更新 AAR:改完 Java 必须重新编译 AAR、替换 nativeplugins 里的旧文件。
6. 正式工程设计:业务页面不要直接调用原生插件
前面的测试页直接调用 uni.requireNativePlugin(),目的是缩短排障链路。正式页面如果都这样写,会迅速出现平台判断重复、回调格式不一致、超时无法处理和厂家字段扩散等问题。
推荐目录:
services/device/
├─ index.js
├─ native-adapter.js
├─ unsupported-adapter.js
└─ result.js
6.1 统一结果模型
services/device/result.js:
export function success(data = null, message = '操作成功') {
return {
success: true,
code: 'SUCCESS',
message,
data
}
}
export function failure(code, message, data = null) {
return {
success: false,
code,
message,
data
}
}
建议至少区分这些错误码:
| UNSUPPORTED_PLATFORM | 当前不是支持的 Android App-Plus 环境 |
| PLUGIN_NOT_FOUND | 自定义基座或 APK 未包含插件 |
| METHOD_NOT_FOUND | JS、插件或 AAR 版本不一致 |
| INVALID_ARGUMENT | 业务参数不合法 |
| SERVICE_NOT_READY | AIDL/系统服务尚未连接 |
| PERMISSION_DENIED | 权限或系统授权不足 |
| SDK_INIT_FAILED | 厂家 SDK 初始化失败 |
| SDK_CALL_FAILED | 厂家方法抛出运行异常 |
| SDK_LINK_ERROR | 缺类、缺方法或 SDK 版本不兼容 |
| TIMEOUT | 在约定时间内没有收到回调 |
| BUSY | 高风险或耗时操作正在执行 |
6.2 原生适配器:Promise、超时和一次回调
services/device/native-adapter.js:
import { failure } from './result.js'
let nativePlugin = null
// #ifdef APP-PLUS
try {
nativePlugin = uni.requireNativePlugin('DemoDevicePlugin')
} catch (error) {
nativePlugin = null
}
// #endif
function invoke(method, args = [], timeoutMs = 8000) {
return new Promise((resolve) => {
if (!nativePlugin) {
resolve(failure('PLUGIN_NOT_FOUND', '设备插件未包含在当前 APK 中'))
return
}
if (typeof nativePlugin[method] !== 'function') {
resolve(failure('METHOD_NOT_FOUND', `设备插件不支持方法:${method}`))
return
}
let settled = false
const finish = (result) => {
if (settled) return
settled = true
clearTimeout(timer)
resolve(result && typeof result === 'object'
? result
: failure('INVALID_RESULT', '设备插件返回格式无效'))
}
const timer = setTimeout(() => {
finish(failure('TIMEOUT', `设备操作超时:${method}`))
}, timeoutMs)
try {
nativePlugin[method](…args, finish)
} catch (error) {
finish(failure('PLUGIN_CALL_FAILED', '设备插件调用失败'))
}
})
}
export function getDeviceInfo() {
return invoke('getDeviceInfo')
}
export function setWeeklyPowerSchedule(schedule) {
return invoke('setWeeklyPowerSchedule', [schedule], 15000)
}
这里有三个重要边界:
- 超时只表示 JavaScript 不再等待,不能自动取消已经进入厂家 SDK 的操作。
- 插件层仍要保证只回调一次;服务层的 settled 是第二道保护,不是替代原生修复。
- 日志可以记录 method/code/耗时,但不能打印 Token、证书密码、License、身份证号或完整厂家授权参数。
6.3 不支持平台适配器
services/device/unsupported-adapter.js:
import { failure } from './result.js'
function unsupported() {
return Promise.resolve(
failure('UNSUPPORTED_PLATFORM', '当前平台不支持 Android 设备能力')
)
}
export const getDeviceInfo = unsupported
export const setWeeklyPowerSchedule = unsupported
services/device/index.js:
import * as nativeAdapter from './native-adapter.js'
import * as unsupportedAdapter from './unsupported-adapter.js'
let adapter = unsupportedAdapter
// #ifdef APP-PLUS
adapter = nativeAdapter
// #endif
export const getDeviceInfo = (…args) => adapter.getDeviceInfo(…args)
export const setWeeklyPowerSchedule = (…args) => (
adapter.setWeeklyPowerSchedule(…args)
)
页面只消费稳定接口:
import { getDeviceInfo } from '@/services/device/index.js'
const result = await getDeviceInfo()
if (!result.success) {
uni.showToast({ title: result.message, icon: 'none' })
return
}
deviceInfo.value = result.data
6.4 正式调用时序
图 8:从 Vue 页面到厂家固件的完整调用时序
系统服务/固件
厂家 SDK
UniModule
services/device
Vue 页面
系统服务/固件
厂家 SDK
UniModule
services/device
Vue 页面
#mermaid-svg-6qGRHhMHuCpg0PuX{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-6qGRHhMHuCpg0PuX .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-6qGRHhMHuCpg0PuX .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-6qGRHhMHuCpg0PuX .error-icon{fill:#552222;}#mermaid-svg-6qGRHhMHuCpg0PuX .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-6qGRHhMHuCpg0PuX .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-6qGRHhMHuCpg0PuX .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-6qGRHhMHuCpg0PuX .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-6qGRHhMHuCpg0PuX .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-6qGRHhMHuCpg0PuX .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-6qGRHhMHuCpg0PuX .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-6qGRHhMHuCpg0PuX .marker{fill:#333333;stroke:#333333;}#mermaid-svg-6qGRHhMHuCpg0PuX .marker.cross{stroke:#333333;}#mermaid-svg-6qGRHhMHuCpg0PuX svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-6qGRHhMHuCpg0PuX p{margin:0;}#mermaid-svg-6qGRHhMHuCpg0PuX .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-6qGRHhMHuCpg0PuX text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-6qGRHhMHuCpg0PuX .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-6qGRHhMHuCpg0PuX .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-6qGRHhMHuCpg0PuX .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-6qGRHhMHuCpg0PuX .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-6qGRHhMHuCpg0PuX #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-6qGRHhMHuCpg0PuX .sequenceNumber{fill:white;}#mermaid-svg-6qGRHhMHuCpg0PuX #sequencenumber{fill:#333;}#mermaid-svg-6qGRHhMHuCpg0PuX #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-6qGRHhMHuCpg0PuX .messageText{fill:#333;stroke:none;}#mermaid-svg-6qGRHhMHuCpg0PuX .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-6qGRHhMHuCpg0PuX .labelText,#mermaid-svg-6qGRHhMHuCpg0PuX .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-6qGRHhMHuCpg0PuX .loopText,#mermaid-svg-6qGRHhMHuCpg0PuX .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-6qGRHhMHuCpg0PuX .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-6qGRHhMHuCpg0PuX .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-6qGRHhMHuCpg0PuX .noteText,#mermaid-svg-6qGRHhMHuCpg0PuX .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-6qGRHhMHuCpg0PuX .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-6qGRHhMHuCpg0PuX .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-6qGRHhMHuCpg0PuX .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-6qGRHhMHuCpg0PuX .actorPopupMenu{position:absolute;}#mermaid-svg-6qGRHhMHuCpg0PuX .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-6qGRHhMHuCpg0PuX .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-6qGRHhMHuCpg0PuX .actor-man circle,#mermaid-svg-6qGRHhMHuCpg0PuX line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-6qGRHhMHuCpg0PuX :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
getDeviceInfo()
检查平台、插件、方法并启动超时
getDeviceInfo(callback)
参数、权限、服务状态校验
调用脱敏厂家方法
Binder/AIDL/系统调用
原始结果
原始字段或异常
success/code/message/data
一次回调保护、取消超时
Promise resolve
7. 原生插件接口设计规则
7.1 参数在 JavaScript 和原生两层校验
服务层做面向业务的校验,原生层做不可绕过的安全校验。以前台周定时计划为例,页面传:
{
"powerOnTime": "07:30",
"powerOffTime": "18:00",
"weekdays": [1, 2, 3, 4, 5]
}
不要让页面直接传厂家底层的 int[]。原生层需要再次验证:
- 时间格式合法,小时 0-23、分钟 0-59。
- 星期只包含允许值、去重后至少一个。
- 当前设备与固件支持对应模式。
- 同一高风险操作没有正在执行。
- 业务语义转换到厂家数组时,星期起点和参数顺序有真机依据。
7.2 线程与回调
- 只做很短的参数处理或 UI 交互时可使用 uiThread = true。
- 文件、摄像头、网络、Binder 等可能阻塞的操作不要长期占用主线程。
- 厂家回调在哪个线程触发必须确认;需要 UI/Activity 操作时切回主线程。
- 每个接口只结束一次;成功、失败、异常、超时和 Activity 销毁不能竞争着重复回调。
- callback == null 时安全返回;异步保存 callback 时要有释放和超时策略。
7.3 生命周期和资源释放
原生层统一管理:AIDL 连接、广播、Camera、线程池、文件流、Handler、ServiceConnection 和监听器。页面反复进入退出、应用前后台切换或进程重启后,不得重复注册或泄漏资源。
图 9:原生资源初始化、恢复与释放生命周期
#mermaid-svg-fyGRogA0ExJhFwlF{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-fyGRogA0ExJhFwlF .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-fyGRogA0ExJhFwlF .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-fyGRogA0ExJhFwlF .error-icon{fill:#552222;}#mermaid-svg-fyGRogA0ExJhFwlF .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-fyGRogA0ExJhFwlF .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-fyGRogA0ExJhFwlF .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-fyGRogA0ExJhFwlF .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-fyGRogA0ExJhFwlF .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-fyGRogA0ExJhFwlF .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-fyGRogA0ExJhFwlF .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-fyGRogA0ExJhFwlF .marker{fill:#333333;stroke:#333333;}#mermaid-svg-fyGRogA0ExJhFwlF .marker.cross{stroke:#333333;}#mermaid-svg-fyGRogA0ExJhFwlF svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-fyGRogA0ExJhFwlF p{margin:0;}#mermaid-svg-fyGRogA0ExJhFwlF .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-fyGRogA0ExJhFwlF .cluster-label text{fill:#333;}#mermaid-svg-fyGRogA0ExJhFwlF .cluster-label span{color:#333;}#mermaid-svg-fyGRogA0ExJhFwlF .cluster-label span p{background-color:transparent;}#mermaid-svg-fyGRogA0ExJhFwlF .label text,#mermaid-svg-fyGRogA0ExJhFwlF span{fill:#333;color:#333;}#mermaid-svg-fyGRogA0ExJhFwlF .node rect,#mermaid-svg-fyGRogA0ExJhFwlF .node circle,#mermaid-svg-fyGRogA0ExJhFwlF .node ellipse,#mermaid-svg-fyGRogA0ExJhFwlF .node polygon,#mermaid-svg-fyGRogA0ExJhFwlF .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-fyGRogA0ExJhFwlF .rough-node .label text,#mermaid-svg-fyGRogA0ExJhFwlF .node .label text,#mermaid-svg-fyGRogA0ExJhFwlF .image-shape .label,#mermaid-svg-fyGRogA0ExJhFwlF .icon-shape .label{text-anchor:middle;}#mermaid-svg-fyGRogA0ExJhFwlF .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-fyGRogA0ExJhFwlF .rough-node .label,#mermaid-svg-fyGRogA0ExJhFwlF .node .label,#mermaid-svg-fyGRogA0ExJhFwlF .image-shape .label,#mermaid-svg-fyGRogA0ExJhFwlF .icon-shape .label{text-align:center;}#mermaid-svg-fyGRogA0ExJhFwlF .node.clickable{cursor:pointer;}#mermaid-svg-fyGRogA0ExJhFwlF .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-fyGRogA0ExJhFwlF .arrowheadPath{fill:#333333;}#mermaid-svg-fyGRogA0ExJhFwlF .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-fyGRogA0ExJhFwlF .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-fyGRogA0ExJhFwlF .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-fyGRogA0ExJhFwlF .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-fyGRogA0ExJhFwlF .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-fyGRogA0ExJhFwlF .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-fyGRogA0ExJhFwlF .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-fyGRogA0ExJhFwlF .cluster text{fill:#333;}#mermaid-svg-fyGRogA0ExJhFwlF .cluster span{color:#333;}#mermaid-svg-fyGRogA0ExJhFwlF div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-fyGRogA0ExJhFwlF .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-fyGRogA0ExJhFwlF rect.text{fill:none;stroke-width:0;}#mermaid-svg-fyGRogA0ExJhFwlF .icon-shape,#mermaid-svg-fyGRogA0ExJhFwlF .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-fyGRogA0ExJhFwlF .icon-shape p,#mermaid-svg-fyGRogA0ExJhFwlF .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-fyGRogA0ExJhFwlF .icon-shape .label rect,#mermaid-svg-fyGRogA0ExJhFwlF .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-fyGRogA0ExJhFwlF .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-fyGRogA0ExJhFwlF .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-fyGRogA0ExJhFwlF :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
前后台切换
服务断开
最终销毁
App/Module 创建
幂等初始化
注册监听或绑定服务
可用状态
生命周期事件
按能力暂停/恢复
标记不可用并有限重连
解绑、注销、关闭与清空引用
不可再向旧页面回调
7.4 权限与设备特性
权限必须同时考虑 Manifest 声明、运行时授权和厂家固件授权。普通 App 声明系统级权限不代表系统会授予。摄像头等不是所有设备必备的硬件应声明为可选,例如:
<uses-permission android:name="android.permission.CAMERA" />
<uses-feature
android:name="android.hardware.camera.any"
android:required="false" />
脱敏项目实测中,厂家 JAR 没有 Camera API,因此单独使用 Android 标准 Camera 完成预览与 JPEG 保存。这个结论说明“厂家 JAR 不提供”不等于“Android 做不到”,但也不能凭空假设所有目标设备都有摄像头。
7.5 高风险能力分级
| 只读 | 设备信息、版本、计划回读 | 超时、错误码、日志 |
| 可逆写入 | 亮度、导航栏、计划设置 | 参数校验、回读、恢复入口 |
| 中断进程 | 重启、关机 | 二次确认、防连点、执行前先回执 |
| 系统级高风险 | Launcher、静默安装、ROOT、固件升级、看门狗 | 隐藏维护入口、授权、恢复方案、独立真机验收 |
会导致 App 立即终止的命令不能等待“关机后的成功回调”。正确语义通常是先返回或上报 COMMAND_ACCEPTED,设备下次启动后再依据真实结果补充闭环。
8. Android Studio 离线打包与 HBuilderX 云打包对比
| Java 插件形式 | 源码 Module | 编译成 AAR |
| 改了 Java 代码后 | 直接编译,秒级 | 重新打 AAR → 替换 → 打基座,很慢 |
| 能断点调试 Java | 能 | 不能 |
| 改前端后出 APK | HBuilderX 生成资源 + 复制 + Gradle 编译 | HBuilderX 云打包 |
| 需要 Android Studio | 每次出 APK 都要 | 只需要打 AAR 的时候 |
| 适合场景 | Java 还在调 | Java 完全稳定后 |
路线选择不是永久决定。脱敏项目采用的实际节奏是:先用离线宿主快速验证 Java 和设备,插件稳定后同步薄 AAR 到 nativeplugins,最终再用匹配版本的正式 Runtime 云包全量回归。
9. 真实设备项目中的实测结论与适用边界
下面不是推测,而是从真实项目过程整理出的可发布结论。所有身份、路径、厂家方法和文件名已经替换。
| 最小基线 | 空项目、签名 APK、U 盘安装和简单点击通过 | AppID、包名、签名、ABI、Runtime、资源和设备安装链路成立 | 再一次只增加一个变量 |
| Runtime 错配 | 新版页面资源装入旧一版离线宿主仍能开发运行,但会提示版本不匹配 | 可作为明确知情的开发临时方案 | 不能作为交付包;最终必须匹配 Runtime 并全量回归 |
| 云打包排队 | 提交后长时间排队 | 云端队列慢不等于源码或插件编译慢 | 本地宿主可并行开发,避免重复提交相同任务 |
| ABI 安装失败 | 云包只有 arm64-v8a,32 位设备显示“应用未安装” | aapt/ADB 证实 NO_MATCHING_ABIS | 专用 32 位设备只打 armeabi-v7a;换设备重新判断 |
| 首页只剩背景 | 启动页正常,业务首页挂载后空白 | 优先查业务 JavaScript 在 App-Plus/旧引擎中的异常 | H5 DOM API 必须条件编译,使用 uni API 获取窗口和监听变化 |
| 生产资源路径 | HBuilderX App 资源导出被非 ASCII 生产路径影响 | 进入 APK 的路径统一短、稳定、ASCII | 文档和设计稿备份目录可保留中文,但不进入生产 static/ |
| 厂家 JAR | 薄 AAR 与独立 JAR 组合运行正常 | 厂家类只能有一个来源 | AAR 内嵌和 android/libs 不能并存同一 JAR |
| 定时开关机 | 写入、回读、真实关机、关机后计划开机通过 | 以固件真实行为闭环,不以“请求成功”判定 | 最终正式 Runtime、断网、跨天、拔电仍要复测 |
| 截图 | 厂家方法返回 false,但本次调用确实生成有效图片 | 检查文件新增/更新时间、大小非零、实际可打开 | 返回布尔值只能作为证据之一 |
| 摄像头 | 厂家 JAR 无 Camera API | Android 标准 Camera 完成枚举、预览、JPEG、媒体扫描和图库查看 | 人脸识别应从已验证 JPEG 单次调用开始 |
| 默认 Launcher | 系统查询仍显示解析器或 false,但重启自动进入 App,退出后系统再次拉起 App | 重启和 HOME 行为比不可靠查询字段更权威 | 恢复系统桌面能力只放维护入口 |
| 开机动画 | 厂家方法无明确成功返回 | 校验 ZIP 后调用,并通过重启肉眼观察判定 | 无恢复 API 时替换前必须具备厂家恢复方案 |
| 静默安装 | 方法接受命令,包名和签名检查通过 | 只说明命令已被接受 | 更高 versionCode、实际版本变化、进程恢复和配置保留仍需补测 |
9.1 为什么要按 Step 逐层增加变量
图 10:从最小安装基线到正式候选包的递进过程
#mermaid-svg-PpaT6J7rm8g4uxzJ{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-PpaT6J7rm8g4uxzJ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-PpaT6J7rm8g4uxzJ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-PpaT6J7rm8g4uxzJ .error-icon{fill:#552222;}#mermaid-svg-PpaT6J7rm8g4uxzJ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-PpaT6J7rm8g4uxzJ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-PpaT6J7rm8g4uxzJ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-PpaT6J7rm8g4uxzJ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-PpaT6J7rm8g4uxzJ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-PpaT6J7rm8g4uxzJ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-PpaT6J7rm8g4uxzJ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-PpaT6J7rm8g4uxzJ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-PpaT6J7rm8g4uxzJ .marker.cross{stroke:#333333;}#mermaid-svg-PpaT6J7rm8g4uxzJ svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-PpaT6J7rm8g4uxzJ p{margin:0;}#mermaid-svg-PpaT6J7rm8g4uxzJ .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-PpaT6J7rm8g4uxzJ .cluster-label text{fill:#333;}#mermaid-svg-PpaT6J7rm8g4uxzJ .cluster-label span{color:#333;}#mermaid-svg-PpaT6J7rm8g4uxzJ .cluster-label span p{background-color:transparent;}#mermaid-svg-PpaT6J7rm8g4uxzJ .label text,#mermaid-svg-PpaT6J7rm8g4uxzJ span{fill:#333;color:#333;}#mermaid-svg-PpaT6J7rm8g4uxzJ .node rect,#mermaid-svg-PpaT6J7rm8g4uxzJ .node circle,#mermaid-svg-PpaT6J7rm8g4uxzJ .node ellipse,#mermaid-svg-PpaT6J7rm8g4uxzJ .node polygon,#mermaid-svg-PpaT6J7rm8g4uxzJ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-PpaT6J7rm8g4uxzJ .rough-node .label text,#mermaid-svg-PpaT6J7rm8g4uxzJ .node .label text,#mermaid-svg-PpaT6J7rm8g4uxzJ .image-shape .label,#mermaid-svg-PpaT6J7rm8g4uxzJ .icon-shape .label{text-anchor:middle;}#mermaid-svg-PpaT6J7rm8g4uxzJ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-PpaT6J7rm8g4uxzJ .rough-node .label,#mermaid-svg-PpaT6J7rm8g4uxzJ .node .label,#mermaid-svg-PpaT6J7rm8g4uxzJ .image-shape .label,#mermaid-svg-PpaT6J7rm8g4uxzJ .icon-shape .label{text-align:center;}#mermaid-svg-PpaT6J7rm8g4uxzJ .node.clickable{cursor:pointer;}#mermaid-svg-PpaT6J7rm8g4uxzJ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-PpaT6J7rm8g4uxzJ .arrowheadPath{fill:#333333;}#mermaid-svg-PpaT6J7rm8g4uxzJ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-PpaT6J7rm8g4uxzJ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-PpaT6J7rm8g4uxzJ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-PpaT6J7rm8g4uxzJ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-PpaT6J7rm8g4uxzJ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-PpaT6J7rm8g4uxzJ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-PpaT6J7rm8g4uxzJ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-PpaT6J7rm8g4uxzJ .cluster text{fill:#333;}#mermaid-svg-PpaT6J7rm8g4uxzJ .cluster span{color:#333;}#mermaid-svg-PpaT6J7rm8g4uxzJ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-PpaT6J7rm8g4uxzJ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-PpaT6J7rm8g4uxzJ rect.text{fill:none;stroke-width:0;}#mermaid-svg-PpaT6J7rm8g4uxzJ .icon-shape,#mermaid-svg-PpaT6J7rm8g4uxzJ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-PpaT6J7rm8g4uxzJ .icon-shape p,#mermaid-svg-PpaT6J7rm8g4uxzJ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-PpaT6J7rm8g4uxzJ .icon-shape .label rect,#mermaid-svg-PpaT6J7rm8g4uxzJ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-PpaT6J7rm8g4uxzJ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-PpaT6J7rm8g4uxzJ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-PpaT6J7rm8g4uxzJ :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
否
是
Step 0:最小页面和安装
真机通过?
只查身份、签名、ABI、Runtime、资源和安装
加入横屏/全屏
加入原生桥接 sayHi
加入厂家只读方法
加入可逆写操作和回读
逐项验证高风险能力
迁移正式页面和后端闭环
匹配 Runtime 的正式候选包
全量真机回归
一次同时换 AppID、包名、证书、页面、ABI、Runtime 和插件,失败后几乎无法归因。最小基线不是额外工作,而是后续每次回退和对照的证据。
9.2 截图等“不可靠返回值”的判定模型
图 11:厂家返回值不可靠时的客观结果判定
#mermaid-svg-MzPQWbPq50Zs9TBp{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-MzPQWbPq50Zs9TBp .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-MzPQWbPq50Zs9TBp .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-MzPQWbPq50Zs9TBp .error-icon{fill:#552222;}#mermaid-svg-MzPQWbPq50Zs9TBp .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-MzPQWbPq50Zs9TBp .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-MzPQWbPq50Zs9TBp .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-MzPQWbPq50Zs9TBp .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-MzPQWbPq50Zs9TBp .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-MzPQWbPq50Zs9TBp .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-MzPQWbPq50Zs9TBp .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-MzPQWbPq50Zs9TBp .marker{fill:#333333;stroke:#333333;}#mermaid-svg-MzPQWbPq50Zs9TBp .marker.cross{stroke:#333333;}#mermaid-svg-MzPQWbPq50Zs9TBp svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-MzPQWbPq50Zs9TBp p{margin:0;}#mermaid-svg-MzPQWbPq50Zs9TBp .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-MzPQWbPq50Zs9TBp .cluster-label text{fill:#333;}#mermaid-svg-MzPQWbPq50Zs9TBp .cluster-label span{color:#333;}#mermaid-svg-MzPQWbPq50Zs9TBp .cluster-label span p{background-color:transparent;}#mermaid-svg-MzPQWbPq50Zs9TBp .label text,#mermaid-svg-MzPQWbPq50Zs9TBp span{fill:#333;color:#333;}#mermaid-svg-MzPQWbPq50Zs9TBp .node rect,#mermaid-svg-MzPQWbPq50Zs9TBp .node circle,#mermaid-svg-MzPQWbPq50Zs9TBp .node ellipse,#mermaid-svg-MzPQWbPq50Zs9TBp .node polygon,#mermaid-svg-MzPQWbPq50Zs9TBp .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-MzPQWbPq50Zs9TBp .rough-node .label text,#mermaid-svg-MzPQWbPq50Zs9TBp .node .label text,#mermaid-svg-MzPQWbPq50Zs9TBp .image-shape .label,#mermaid-svg-MzPQWbPq50Zs9TBp .icon-shape .label{text-anchor:middle;}#mermaid-svg-MzPQWbPq50Zs9TBp .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-MzPQWbPq50Zs9TBp .rough-node .label,#mermaid-svg-MzPQWbPq50Zs9TBp .node .label,#mermaid-svg-MzPQWbPq50Zs9TBp .image-shape .label,#mermaid-svg-MzPQWbPq50Zs9TBp .icon-shape .label{text-align:center;}#mermaid-svg-MzPQWbPq50Zs9TBp .node.clickable{cursor:pointer;}#mermaid-svg-MzPQWbPq50Zs9TBp .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-MzPQWbPq50Zs9TBp .arrowheadPath{fill:#333333;}#mermaid-svg-MzPQWbPq50Zs9TBp .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-MzPQWbPq50Zs9TBp .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-MzPQWbPq50Zs9TBp .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-MzPQWbPq50Zs9TBp .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-MzPQWbPq50Zs9TBp .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-MzPQWbPq50Zs9TBp .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-MzPQWbPq50Zs9TBp .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-MzPQWbPq50Zs9TBp .cluster text{fill:#333;}#mermaid-svg-MzPQWbPq50Zs9TBp .cluster span{color:#333;}#mermaid-svg-MzPQWbPq50Zs9TBp div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-MzPQWbPq50Zs9TBp .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-MzPQWbPq50Zs9TBp rect.text{fill:none;stroke-width:0;}#mermaid-svg-MzPQWbPq50Zs9TBp .icon-shape,#mermaid-svg-MzPQWbPq50Zs9TBp .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-MzPQWbPq50Zs9TBp .icon-shape p,#mermaid-svg-MzPQWbPq50Zs9TBp .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-MzPQWbPq50Zs9TBp .icon-shape .label rect,#mermaid-svg-MzPQWbPq50Zs9TBp .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-MzPQWbPq50Zs9TBp .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-MzPQWbPq50Zs9TBp .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-MzPQWbPq50Zs9TBp :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
否
是
否
是
厂家返回 false
调用前记录目标文件状态
调用厂家方法
等待有限时间并重新读取文件
文件是否本次新增或更新?
FAILED:没有客观结果
非空且能解析/打开?
SUCCESS:记录厂家返回值与文件证据
这套方法只适合有客观副作用证据的接口。不能把所有 false 都忽略;若没有可靠文件、回读或硬件行为,就只能报告失败或“不确定”。
10. APK 构建后的静态校验与发布门禁
设 APK 路径为:
$apk = 'C:\\workspace\\ClassBoardDemo\\output\\classboard-release.apk'
10.1 校验包名、版本、SDK 与 ABI
aapt.exe dump badging $apk
核对:
- package name 是预期 applicationId。
- versionCode 单调递增,versionName 与发布记录一致。
- sdkVersion 不高于目标设备 API。
- native-code 包含目标设备 ABI。
10.2 校验最终 APK 签名
apksigner.bat verify —verbose —print-certs $apk
旧 Android 设备至少确认 V1 签名通过,同时核对最终 APK 的 SHA-1/SHA-256 与 DCloud 平台信息一致。不要只检查 keystore,因为构建任务可能没有真正使用它。
10.3 校验 ZIP 对齐与文件哈希
zipalign.exe –c –v 4 $apk
Get-Item $apk | Select-Object FullName, Length, LastWriteTime
Get-FileHash $apk –Algorithm SHA256
10.4 检查页面资源、插件类和厂家类
检查最终 APK:
- assets/apps/__UNI__A1B2C3D/www/ 存在。
- dcloud_control.xml 指向同一 AppID。
- DemoDeviceModule 和厂家入口类存在。
- 厂家入口类只有一个来源。
- 没有旧 AppID、示例页面、大型无关资源或多余 ABI。
10.5 使用 ADB 安装并获取真实错误码
adb devices
adb install –r $apk
旧设备文件管理器往往只显示“应用未安装”或“解析失败”。ADB 的 INSTALL_FAILED_UPDATE_INCOMPATIBLE、INSTALL_FAILED_NO_MATCHING_ABIS、INSTALL_FAILED_OLDER_SDK、INSTALL_FAILED_VERSION_DOWNGRADE 等错误码才有定位价值。
图 12:APK 从生成到真机发布的质量门禁
#mermaid-svg-kwY4T1UtkId9ff5C{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-kwY4T1UtkId9ff5C .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-kwY4T1UtkId9ff5C .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-kwY4T1UtkId9ff5C .error-icon{fill:#552222;}#mermaid-svg-kwY4T1UtkId9ff5C .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-kwY4T1UtkId9ff5C .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-kwY4T1UtkId9ff5C .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-kwY4T1UtkId9ff5C .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-kwY4T1UtkId9ff5C .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-kwY4T1UtkId9ff5C .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-kwY4T1UtkId9ff5C .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-kwY4T1UtkId9ff5C .marker{fill:#333333;stroke:#333333;}#mermaid-svg-kwY4T1UtkId9ff5C .marker.cross{stroke:#333333;}#mermaid-svg-kwY4T1UtkId9ff5C svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-kwY4T1UtkId9ff5C p{margin:0;}#mermaid-svg-kwY4T1UtkId9ff5C .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-kwY4T1UtkId9ff5C .cluster-label text{fill:#333;}#mermaid-svg-kwY4T1UtkId9ff5C .cluster-label span{color:#333;}#mermaid-svg-kwY4T1UtkId9ff5C .cluster-label span p{background-color:transparent;}#mermaid-svg-kwY4T1UtkId9ff5C .label text,#mermaid-svg-kwY4T1UtkId9ff5C span{fill:#333;color:#333;}#mermaid-svg-kwY4T1UtkId9ff5C .node rect,#mermaid-svg-kwY4T1UtkId9ff5C .node circle,#mermaid-svg-kwY4T1UtkId9ff5C .node ellipse,#mermaid-svg-kwY4T1UtkId9ff5C .node polygon,#mermaid-svg-kwY4T1UtkId9ff5C .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-kwY4T1UtkId9ff5C .rough-node .label text,#mermaid-svg-kwY4T1UtkId9ff5C .node .label text,#mermaid-svg-kwY4T1UtkId9ff5C .image-shape .label,#mermaid-svg-kwY4T1UtkId9ff5C .icon-shape .label{text-anchor:middle;}#mermaid-svg-kwY4T1UtkId9ff5C .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-kwY4T1UtkId9ff5C .rough-node .label,#mermaid-svg-kwY4T1UtkId9ff5C .node .label,#mermaid-svg-kwY4T1UtkId9ff5C .image-shape .label,#mermaid-svg-kwY4T1UtkId9ff5C .icon-shape .label{text-align:center;}#mermaid-svg-kwY4T1UtkId9ff5C .node.clickable{cursor:pointer;}#mermaid-svg-kwY4T1UtkId9ff5C .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-kwY4T1UtkId9ff5C .arrowheadPath{fill:#333333;}#mermaid-svg-kwY4T1UtkId9ff5C .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-kwY4T1UtkId9ff5C .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-kwY4T1UtkId9ff5C .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-kwY4T1UtkId9ff5C .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-kwY4T1UtkId9ff5C .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-kwY4T1UtkId9ff5C .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-kwY4T1UtkId9ff5C .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-kwY4T1UtkId9ff5C .cluster text{fill:#333;}#mermaid-svg-kwY4T1UtkId9ff5C .cluster span{color:#333;}#mermaid-svg-kwY4T1UtkId9ff5C div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-kwY4T1UtkId9ff5C .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-kwY4T1UtkId9ff5C rect.text{fill:none;stroke-width:0;}#mermaid-svg-kwY4T1UtkId9ff5C .icon-shape,#mermaid-svg-kwY4T1UtkId9ff5C .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-kwY4T1UtkId9ff5C .icon-shape p,#mermaid-svg-kwY4T1UtkId9ff5C .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-kwY4T1UtkId9ff5C .icon-shape .label rect,#mermaid-svg-kwY4T1UtkId9ff5C .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-kwY4T1UtkId9ff5C .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-kwY4T1UtkId9ff5C .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-kwY4T1UtkId9ff5C :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
APK 已生成
aapt:身份/版本/SDK/ABI
apksigner:V1/V2 与证书
zipalign + SHA-256
检查 www、插件类和厂家类
ADB/U 盘安装
冷启动与基础桥接
厂家设备真实行为
保存证据并决定是否可发布
11. 真机验收矩阵:什么才算真正通过
11.1 基础链路
- 首次安装、覆盖安装、冷启动和进程被杀后重启。
- 页面构建标识与本次 APK 对应,避免误测旧资源。
- sayHi、设备只读信息和结构化失败回调。
- 插件缺失、方法缺失、SDK 初始化失败和服务未就绪。
- 页面反复进入退出、前后台切换和 Activity 重建。
- 断网、网络恢复和设备重启后的恢复策略。
11.2 写操作和真实设备行为
- 参数边界、非法值、重复点击和并发保护。
- 写入后回读一致,而不是只检查 Java 方法未抛异常。
- 截图/文件以新增、大小、格式和可打开作为证据。
- 定时计划覆盖设置、清除、断网、跨天、拔电和系统时间。
- 关机后自动开机与开机后自动进入 App 分开验收。
- Launcher、导航栏、开机动画均有受控恢复路径。
- 静默升级验证更高版本实际安装、启动恢复和配置保留。
11.3 正式交付候选包
- HBuilderX 页面资源与 DCloud Android Runtime 版本匹配。
- 使用正式 AppID、包名、AppKey、证书和 ABI。
- Release 包经过混淆/不混淆实际配置下的插件回归。
- APK 包名、版本、签名、大小、SHA-256 和构建时间已记录。
- 厂家 SDK/AAR 版本和私有哈希记录完整,但不写入公开文档。
- 目标设备型号、固件、Android、API 和测试时间写入私有验收记录。
- 未完成项明确标成“未验证”,不使用“应该可用”。
12. 常见问题与分层排障
先按故障阶段分流
图 13:按照失败层级进行排障
#mermaid-svg-Mtzx06IInwngXyoy{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Mtzx06IInwngXyoy .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Mtzx06IInwngXyoy .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Mtzx06IInwngXyoy .error-icon{fill:#552222;}#mermaid-svg-Mtzx06IInwngXyoy .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Mtzx06IInwngXyoy .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Mtzx06IInwngXyoy .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Mtzx06IInwngXyoy .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Mtzx06IInwngXyoy .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Mtzx06IInwngXyoy .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Mtzx06IInwngXyoy .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Mtzx06IInwngXyoy .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Mtzx06IInwngXyoy .marker.cross{stroke:#333333;}#mermaid-svg-Mtzx06IInwngXyoy svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Mtzx06IInwngXyoy p{margin:0;}#mermaid-svg-Mtzx06IInwngXyoy .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-Mtzx06IInwngXyoy .cluster-label text{fill:#333;}#mermaid-svg-Mtzx06IInwngXyoy .cluster-label span{color:#333;}#mermaid-svg-Mtzx06IInwngXyoy .cluster-label span p{background-color:transparent;}#mermaid-svg-Mtzx06IInwngXyoy .label text,#mermaid-svg-Mtzx06IInwngXyoy span{fill:#333;color:#333;}#mermaid-svg-Mtzx06IInwngXyoy .node rect,#mermaid-svg-Mtzx06IInwngXyoy .node circle,#mermaid-svg-Mtzx06IInwngXyoy .node ellipse,#mermaid-svg-Mtzx06IInwngXyoy .node polygon,#mermaid-svg-Mtzx06IInwngXyoy .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Mtzx06IInwngXyoy .rough-node .label text,#mermaid-svg-Mtzx06IInwngXyoy .node .label text,#mermaid-svg-Mtzx06IInwngXyoy .image-shape .label,#mermaid-svg-Mtzx06IInwngXyoy .icon-shape .label{text-anchor:middle;}#mermaid-svg-Mtzx06IInwngXyoy .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Mtzx06IInwngXyoy .rough-node .label,#mermaid-svg-Mtzx06IInwngXyoy .node .label,#mermaid-svg-Mtzx06IInwngXyoy .image-shape .label,#mermaid-svg-Mtzx06IInwngXyoy .icon-shape .label{text-align:center;}#mermaid-svg-Mtzx06IInwngXyoy .node.clickable{cursor:pointer;}#mermaid-svg-Mtzx06IInwngXyoy .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Mtzx06IInwngXyoy .arrowheadPath{fill:#333333;}#mermaid-svg-Mtzx06IInwngXyoy .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Mtzx06IInwngXyoy .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Mtzx06IInwngXyoy .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Mtzx06IInwngXyoy .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Mtzx06IInwngXyoy .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Mtzx06IInwngXyoy .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Mtzx06IInwngXyoy .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Mtzx06IInwngXyoy .cluster text{fill:#333;}#mermaid-svg-Mtzx06IInwngXyoy .cluster span{color:#333;}#mermaid-svg-Mtzx06IInwngXyoy div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Mtzx06IInwngXyoy .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Mtzx06IInwngXyoy rect.text{fill:none;stroke-width:0;}#mermaid-svg-Mtzx06IInwngXyoy .icon-shape,#mermaid-svg-Mtzx06IInwngXyoy .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Mtzx06IInwngXyoy .icon-shape p,#mermaid-svg-Mtzx06IInwngXyoy .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Mtzx06IInwngXyoy .icon-shape .label rect,#mermaid-svg-Mtzx06IInwngXyoy .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Mtzx06IInwngXyoy .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Mtzx06IInwngXyoy .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Mtzx06IInwngXyoy :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
Gradle 没生成 APK
APK 无法安装
能启动但白屏
插件找不到
插件可调但厂家失败
返回成功但设备没动作
失败发生在哪一层?
构建层:JDK/Gradle/依赖/Manifest/源码
安装层:签名/版本/SDK/ABI/文件完整性
页面层:AppID/www/Runtime/业务 JS 异常
注册层:插件 ID/类名/AAR/基座
SDK 层:JAR/权限/AIDL/固件/线程
行为层:回读/文件/重启/现场观察
先找第一条根因,不要在安装失败时改 Vue 页面,也不要在插件注册失败时反复调整厂家参数。
HBuilderX 只生成 resources,没有 APK
正常。“生成本地打包 App 资源”只产出 www,需要同步到 Android 离线宿主再由 Gradle 生成 APK;若要让 HBuilderX 直接得到 APK,应使用云打包菜单。
AppKey 校验失败
依次核对:AppID、Gradle applicationId、AndroidManifest 中的 dcloud_appkey、最终 APK 签名 SHA-1、DCloud 后台绑定信息。注意检查的是最终 APK,而不是“本来打算使用”的证书。
安装提示签名不一致
设备已有同包名、不同签名的 APK。要么使用原签名重新构建,要么在确认本地数据影响后卸载旧包。不能通过修改 versionName 解决签名冲突。
无法覆盖升级
必须同时满足:相同包名、相同签名、versionCode 更大。仅提高 versionName 无效。
Duplicate class
同一厂家 JAR 或依赖被源码 Module、AAR、app/libs、nativeplugins/android/libs 或 Maven 依赖重复携带。检查依赖树和 AAR 压缩内容,保证每个类只有一个来源,不要靠随机删除文件碰运气。
JAVA_HOME 未设置或 JDK 不兼容
定位 Android Studio 自带的 jbr,让 Android Studio Gradle JDK 和 Terminal JAVA_HOME 使用同一兼容版本。无需因此重新下载全部 Android SDK。
Android 5.x 只显示“应用未安装”
旧系统安装器隐藏了真实原因。按顺序检查:
NoClassDefFoundError
编译期能看到类,运行时 APK 中没有。常见原因是厂家 JAR 只有 compileOnly 却没有任何运行时提供者、本地插件目录漏放 JAR,或 AAR 并没有像预期那样内嵌依赖。直接检查最终 APK。
NoSuchMethodError
编译使用的 JAR 和 APK/固件实际加载的版本不一致,或厂家文档与 JAR 签名不一致。记录两份文件哈希,用 javap 检查实际签名,并排查设备系统是否预装了同包名旧版本类库。
requireNativePlugin() 返回空或方法不存在
检查插件 ID、dcloud_uniplugins.json/package.json 类名、AAR 是否更新、manifest.json 是否启用插件,以及当前运行的是不是包含插件的自定义基座。标准基座和 H5 无法验证新增 Android 插件。
启动页正常,进入首页后只剩背景
这通常说明宿主已经找到 www,但业务页面在挂载阶段发生 JavaScript 异常。旧 Android/App-Plus 尤其检查:
- window、document、closest()、鼠标滚轮等浏览器 DOM API 是否只在 H5 分支使用。
- replaceAll() 等旧 JavaScript 引擎不支持的方法是否有兼容写法。
- 页面尺寸是否使用 uni.getWindowInfo(),并为旧版本保留 uni.getSystemInfoSync() 降级。
- 窗口变化是否使用 uni.onWindowResize() / uni.offWindowResize()。
- logcat 或 HBuilderX 控制台的第一条业务异常是什么。
方法调用成功,但目标设备没有动作
先确认“成功”的定义。Java 方法未抛异常、厂家返回 true、系统查询字段变化和真实硬件行为不是同一层证据。能回读就回读;能检查文件就检查文件;涉及 Launcher、开机、关机和开机动画就执行受控重启并现场观察。
Release 构建被 targetSdk Lint 拦截
先判断 APK 是否只部署到受控专用设备,还是还要上架应用商店。只有在明确不走 Google Play、目标旧设备必须保持当前兼容配置,并记录风险时,才可以针对具体 Lint 项做最小范围抑制。不能为了让构建变绿就关闭所有 Lint。
Java 报 非法字符: '\\ufeff'
文件带 UTF-8 BOM。移除报错文件头部 BOM,再扫描本次涉及的所有 .java 文件,确认不存在 EF BB BF,重新编译验证。修编码时不要顺手修改业务逻辑。
13. 总结:从“能编译”走到“能交付”
两条路线的目标功能可以一致,但构建环境、Runtime、依赖合并、签名和混淆链路不同,所以每条路线的最终 APK 都需要独立验包和真机回归。新手先用路线一跑通最小桥接和厂家只读能力,再冻结插件产物走路线二,定位问题会清楚很多。
真正可交付的标准不是“Gradle 显示成功”,而是身份、资源、插件、厂家 SDK、签名、ABI 和目标设备行为形成完整证据链。遇到问题时保留第一条根因、APK 哈希、设备环境和复现步骤,排障效率会高得多。
如果只记住本文的核心原则,可以归纳为下面八点:
把这八点守住,uni-app 对接自定义 JAR 就不再是一堆靠运气拼起来的配置,而是一条可以逐层验证、可以回退、也可以交付的工程链路。



