欢迎光临
我们一直在努力

uni-app 对接自定义 JAR:Android 原生插件、AAR、离线打包与云打包完整实战

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.* 当作生产包名。

这个包名后面会出现在三个地方,必须完全一致:

  • Android Studio app/build.gradle 里的 applicationId。
  • DCloud 后台“各平台信息”里登记的包名。
  • 最终 APK 的实际包名。
  • 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

    三个必须检查的点:

  • apps 下的文件夹名和 dcloud_control.xml 里的 AppID 完全一致
  • __UNI__A1B2C3D 下面直接是 www,不要多套或少套
  • 旧 AppID 目录暂时留着,验证成功后再清理
  • 这是"搬家"。搬错路径或 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 回答四个问题:

  • 哪些方法需要先绑定,哪些只读方法不需要?
  • 绑定是同步还是异步,如何判断 Ready?
  • 多个页面/Module 共用一个连接时,由谁持有引用并何时解绑?
  • 服务断开、进程重启或 Activity 重建后,如何恢复?
  • 如果厂家 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 步:重新生成资源 + 复制 + 构建

    每次改前端页面都做这三步:

  • HBuilderX → 发行 → 生成本地打包App资源
  • 把 __UNI__A1B2C3D/ 整个复制覆盖到 app/src/main/assets/apps/
  • .\\gradlew.bat :app:assembleDebug
  • 改完页面没重新生成+复制,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 中插件 android/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 只显示“应用未安装”

    旧系统安装器隐藏了真实原因。按顺序检查:

  • apksigner verify –verbose 的 V1 签名为 true。
  • aapt dump badging 的 minSdkVersion 与 native-code 覆盖目标设备。
  • 设备中不存在同包名、不同签名或更高 versionCode 的旧应用。
  • 设备有足够存储空间,APK 从电脑到 U 盘后的大小和哈希未变化。
  • 使用短 ASCII 路径和文件名排除旧文件管理器兼容问题。
  • 优先使用 adb install -r 获取具体 INSTALL_FAILED_*。
  • 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 哈希、设备环境和复现步骤,排障效率会高得多。

    如果只记住本文的核心原则,可以归纳为下面八点:

  • 先跑通官方示例,再复制独立宿主,不直接污染原始 SDK。
  • 先验证 sayHi,再接厂家只读方法,最后才做关机、升级等高风险能力。
  • 页面、设备服务层、UniModule、厂家 JAR 和固件各自负责自己的边界。
  • 同一个厂家类在最终 APK 中只能有一个来源。
  • AppID、包名、最终 APK 签名和 AppKey 必须形成一致身份。
  • BUILD SUCCESSFUL 只代表生成产物,不代表 APK 能安装,更不代表硬件行为生效。
  • 普通手机只能验桥接,厂家固件能力必须在目标设备上验证。
  • 所有“成功”都要尽量用回读、文件、重启或真实硬件行为形成客观证据。
  • 把这八点守住,uni-app 对接自定义 JAR 就不再是一堆靠运气拼起来的配置,而是一条可以逐层验证、可以回退、也可以交付的工程链路。

    赞(0)
    未经允许不得转载:171主机测评 » uni-app 对接自定义 JAR:Android 原生插件、AAR、离线打包与云打包完整实战
    分享到: 更多 (0)

    评论 抢沙发

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址