UniApp 对接优博讯 DT51 UHF RFID 盘点：从「基座不包含插件」到真机扫标签全流程

借你一冬

361人浏览 · 2026-06-24 10:25:56

借你一冬 · 2026-06-24 10:25:56 发布

适用：UniApp / unibest + HBuilderX + 优博讯 DT51/DT50 系列 PDA + 宜联 URFIDLibrary SDK
关键词：uni-app、原生插件、自定义基座、URFID-Reader、UHF 盘点、优博讯

一、背景

仓储 PDA 项目需要在 UniApp 中实现 RFID 超高频盘点：手持优博讯 DT51_5G，设备自带 UHF 模块，官方 UHFDemo 可正常读标签，说明硬件与 SDK 没问题。

目标：在自研 App 的「RFID 盘点」页面中，调用与 UHFDemo 相同的 URFIDLibrary v2.5.1230，实现初始化、开始/停止盘点、回调 EPC。

技术栈：

层级	选型
前端	Vue3 + unibest
打包	HBuilderX 云打包 + 自定义调试基座
原生	本地原生插件 `URFID-Reader`
SDK	`com.ubx.usdk.RFIDSDKManager`（宜联/优博讯）

二、踩过的坑（核心结论）

2.1 报错现象

进入 RFID 页面，控制台反复出现：

[JS Framework] 当前运行的基座不包含原生插件[URFID-Reader]，
请在 manifest 中配置该插件，重新制作包括该原生插件的自定义运行基座

即使：

manifest.json 已勾选 URFID-Reader
nativeplugins 目录存在
云打包「制作自定义调试基座」显示成功
日志里 copy-native-resources 复制插件完成

仍然报错。

2.2 根因（一句话）

UniApp 云打包不会编译 android/ 下的 Java 源码，只打包预编译的 .aar。

我们最初只有：

宜联 SDK：URFIDLibrary-v2.5.1230.aar
Java 桥接类：URFIDReaderModule.java

缺少 桥接模块自己的 AAR（含 URFIDReaderModule 类），所以：

dcloud_uniplugins.json 里可能有注册项
但 APK 里没有可加载的插件类
uni.requireNativePlugin('URFID-Reader') 失败

重复制作 100 次基座也无效，直到补上 URFID-Reader-bridge-release.aar。

2.3 其他易混淆点

现象	是否根因
`package.json` 里 `class` 写错	否，类名与 Java 包名一致即可
`copy-native-resources` 复制到 dist	否，只影响开发目录，不等于基座含插件
设备型号 DT51 vs DT50	否，同 SDK，UHFDemo 能扫即可
广播模式收不到标签	预期，宜联 SDK 必须走原生插件
DCloud 市场云插件	付费，且 API 不同（`Alvin-YbxDT5uModule`）

三、整体架构

┌─────────────────────────────────────────────────────────┐
│  RFID 盘点页 (index.vue)                                 │
│    createRfidReader() → startInventory() / stopInventory │
└──────────────────────────┬──────────────────────────────┘
                           │ uni.requireNativePlugin('URFID-Reader')
┌──────────────────────────▼──────────────────────────────┐
│  URFIDReaderModule (桥接 AAR，需 Android Studio 编译)      │
│    init / startInventory / stopInventory / release       │
│    fireGlobalEventCallback('onUhfInventory', ...)       │
└──────────────────────────┬──────────────────────────────┘
                           │ RFIDSDKManager (宜联 SDK)
┌──────────────────────────▼──────────────────────────────┐
│  URFIDLibrary-v2.5.1230.aar + platform_sdk jar           │
│  优博讯 DT51 UHF 硬件                                     │
└─────────────────────────────────────────────────────────┘

JS 调用链（与 UHFDemo 一致）：

init() → RFIDSDKManager.init
startInventory({ timeout: 0 }) → startInventoryWithTimeout
标签回调 → 全局事件 onUhfInventory → 页面合并 EPC 列表
stopInventory() / release()

四、插件目录规范（云打包用）

DCloud 要求本地插件结构如下：

nativeplugins/URFID-Reader/
├── package.json
└── android/
    ├── URFID-Reader-bridge-release.aar   ← 桥接（必须）
    ├── URFIDLibrary-v2.5.1230.aar        ← 宜联 SDK（放 android 根目录）
    └── libs/
        └── platform_sdk_v3.1.221124.jar

package.json 关键配置：

{
  "id": "URFID-Reader",
  "_dp_nativeplugin": {
    "android": {
      "plugins": [{
        "type": "module",
        "name": "URFID-Reader",
        "class": "io.dcloud.uniplugins.urfid.URFIDReaderModule"
      }],
      "integrateType": "aar",
      "minSdkVersion": "26"
    }
  }
}

注意：

vendor 的 aar 放 android/ 根目录
jar 放 android/libs/
不要把 uniapp-v8-release.aar 打进插件包（仅编译桥接时用）
不要在 android/ 下放 Java 源码指望云打包编译

五、完整实施步骤

5.1 准备 SDK 文件

从厂商 UHF SDK 包获取：

文件	来源
`URFIDLibrary-v2.5.1230.aar`	SDK 包 `libs/`
`platform_sdk_v3.1.221124.jar`	UHFDemo `app(ble)/libs/`

5.2 编译桥接 AAR（关键一步）

HBuilderX → 帮助 → 下载 App 离线 SDK（版本与 HBuilderX 一致）
复制 SDK/libs/uniapp-v8-release.aar 到：
nativeplugins/URFID-Reader/android-build/app-libs/
Android Studio 打开 nativeplugins/URFID-Reader/android-build/
- JVM 选 17（Gradle 8.2 与 JVM 21 不兼容）
- Sync 成功后执行 :urfid-bridge:assembleRelease
复制产物：

urfid-bridge/build/outputs/aar/urfid-bridge-release.aar
  → android/URFID-Reader-bridge-release.aar

.\scripts\verify-urfid-plugin.ps1

四项均 [OK] 再继续。

5.3 manifest 与 HBuilderX 基座

HBuilderX 打开项目根目录（含 nativeplugins/）
src/manifest.json → App 原生插件配置 → 勾选 URFID-Reader
运行 → 制作自定义调试基座（传统打包，非安心打包）
PDA 卸载旧基座 → 使用自定义基座运行 → 本地基座

5.4 真机验证

检查项	预期
进 RFID 页	无「不包含原生插件」
调试区	`插件：URFID-Reader · 模式：native`
开始感应	`URFID init 成功`、`startInventory 成功`
扫标签	按侧键，列表出现 EPC

六、前端封装要点

rfid-reader.ts 核心逻辑：

const URFID_PLUGIN_ID = 'URFID-Reader'

// 仅探测已打包的 URFID-Reader，避免刷其他插件警告
const plugin = uni.requireNativePlugin('URFID-Reader')
plugin.init(callback)
plugin.startInventory({ timeout: 0 }, callback)
// 监听 plus.globalEvent 'onUhfInventory'
plugin.stopInventory(callback)

页面 onMounted 调用 rfidReader.bind()，卸载时 unbind()。

七、Android Studio 编译常见问题

7.1 Gradle JVM 版本

弹窗提示 Gradle 8.2 与 JVM 21 不兼容 → 点 Use JVM 17。

7.2 flatDir 与 settings.gradle 冲突

错误：repository 'flatDir' was added by build file 'urfid-bridge/build.gradle'

解决：去掉 flatDir，依赖改为 compileOnly files('libs/xxx.aar')。

7.3 Cursor / VS Code 没有 Gradle 面板

编 AAR 必须用 Android Studio，Cursor 只能编辑代码，不能 assembleRelease。

八、如何判断基座是否真正包含插件

不要只看「制作基座成功」。

阶段	方法
打包前	`verify-urfid-plugin.ps1` 桥接 AAR 必须 OK
打包后	解压 `android_debug.apk` 看是否有桥接类/aar
运行时	无「不包含插件」+ 调试区 `mode: native`

九、经验总结

本地原生插件 = Java 桥接 AAR + vendor AAR + manifest + 自定义基座，四者缺一不可。
云打包不编 Java，这是反复失败的最大原因。
Android Studio 编译桥接 AAR 只需做一次，除非改 Java 代码。
优博讯 DT51 与 UHFDemo 同 SDK，不必改设备型号适配，也不必买 DCloud 付费云插件（除非不想维护 AAR）。
UHFDemo 能扫 = 硬件 OK，App 侧问题集中在基座与插件集成。

十、参考文件（本项目）

路径	说明
`nativeplugins/URFID-Reader/`	本地原生插件
`nativeplugins/URFID-Reader/android-build/`	Android Studio 编译工程
`nativeplugins/URFID-Reader/快速上手.md`	三步操作说明
`src/utils/rfid-reader.ts`	JS 封装
`src/pages/stocktakingManage/rfid/index.vue`	RFID 盘点页
`scripts/verify-urfid-plugin.ps1`	打包前检查
`scripts/check-debug-base.ps1`	基座 APK 诊断

十一、结语

UniApp 对接 PDA 厂商 UHF SDK 的难点不在 Vue 页面，而在 原生插件 AAR 化 + 自定义基座。把桥接模块用 Android Studio 编出 URFID-Reader-bridge-release.aar 并打进基座后，RFID 盘点即可与 UHFDemo 一样稳定读标签。

若你也在做优博讯 + UniApp RFID，希望本文能帮你少踩「反复制作基座仍不包含插件」的坑。

作者备注：本文基于 uni-app + HBuilderX + 优博讯 DT51_5G + URFIDLibrary v2.5.1230 实际项目整理。
欢迎转载，请注明出处。