6.3 原生插件开发与集成

6.3 原生插件开发与集成

本节导读：当需求落到 uni API 与 plus 都够不着的地方——对接第三方原生 SDK、驱动蓝牙外设、嵌入自研原生页面——原生插件是正规通道。本节讲清何时该上插件、市场上怎么选、集成的完整流程与云打包的关系，并交代 uts 插件这条降低门槛的新路。

判断：什么时候真的需要原生插件

插件有真实的集成成本（包体积、平台审核、维护依赖），上插件前先过三问：uni API 加条件编译能不能覆盖？ 大量"看起来要原生"的需求其实有现成 API（扫码、蓝牙基础操作、剪贴板）。H5 降级能不能接受？ 只在 App 端提供的增强，其他端给降级体验，常常比全端统一划算。自研 SDK 的维护成本养得起吗？ 插件不是写完就结束，宿主系统大版本升级（iOS 新版本、Android 新系统）都要回归。三问过完仍然需要，才进集成流程——商城对接的电子秤蓝牙 SDK 就是过完三问才立项的：uni 蓝牙 API 不支持秤的自定义协议，降级等于砍功能，SDK 由硬件厂商维护联调成本可控。

集成四步：选型、登记、基座、验证

以 uni 原生插件市场的一个蓝牙插件为例走完整流程。第一步选型：看三处——最近更新时间（半年内有维护）、端覆盖（iOS 与 Android 是否都有）、issue 区的响应质量；付费插件先看有没有试用或源码版。第二步登记：插件放进工程的 nativeplugins 目录（本地插件）或在插件市场点"购买并绑定"到应用（云端插件），manifest 里 sources 节点声明插件名与版本。第三步基座：插件是原生代码，标准基座里没有它，必须打自定义基座才能真机调试——这是新手最大卡点：真机运行报"插件不存在"，八成是还在用标准基座。第四步验证：自定义基座装到真机，跑插件的初始化与核心接口，iOS 与 Android 各过一遍。

// manifest.json 片段：声明原生插件（App 端配置，支持条件编译块）
{
  "app-plus": {
    "nativePlugins": {
      "ht-bluetooth-scale": {
        "package": "com.ht.scale",
        "provider": "plugin-provider",
        "version": "1.2.0"
      }
    }
  }
}
​

// 调用侧：与适配层公约一致，插件调用收进 utils 适配层
// utils/scale.js
function getScaleModule() {
  let mod = null;
  // #ifdef APP-PLUS
  mod = uni.requireNativePlugin('ht-bluetooth-scale');
  // #endif
  return mod;
}

export async function readWeight() {
  const mod = getScaleModule();
  // #ifndef APP-PLUS
  uni.showToast({ title: '请在 App 端使用称重', icon: 'none' });
  throw new Error('scale unsupported on this platform');
  // #endif
  return new Promise((resolve, reject) => {
    mod.readWeight((res) => (res.code === 0 ? resolve(res.weight) : reject(res)));
  });
}
​

云打包与插件生效的关系

原生插件的代码最终是在云打包（或本地打包）时编进安装包的，这条时序决定了三件工程事实：改插件配置后必须重新云打包才生效，热更新（wgt）补不了插件变更；云打包机要能取到插件，市场插件自动可达，本地插件随工程上传；插件的权限声明会汇入安装包的权限清单，应用市场审核会看——引一个要通讯录权限的插件，上架时就得回答为什么。把"插件变更必走云打包"写进发版清单，能避免"热更后插件失效"的深夜事故。

图 6-3 原生插件从选型到生效的时序

uts 插件：自研的新通道

自己写原生能力时，传统路线是 Android 写 Kotlin、iOS 写 Object-C/Swift，双端两份代码两拨技能。uts 插件把这条路的门槛砍低：用 uts 语言（TypeScript 语法子集）写一份逻辑，编译期产出 Kotlin 与 Swift 源码。它的定位要摆正：适合逻辑型能力（算法、协议解析、轻量原生调用），重 UI 的复杂原生模块仍建议原生双端实现或市场选型。商城的电子秤协议解析就换成了 uts 插件——一份代码双端生效，前端同学自己就能维护，不再排队等原生排期。

插件集成故障两则

两个高频故障帮助避开集成弯路。故障一，云打包成功但运行时调用插件报方法不存在：多半是 manifest 里声明的插件版本与代码里 require 的模块名不一致，或者云端插件在市场里更新了大版本而工程没跟着升——对着插件的集成文档逐字核对模块名与版本号，两分钟解决半小时的懵。故障二，自定义基座能跑、正式包失效：基座是本地打的、正式包是云打的，两边勾选的原生模块清单不一致；把"打包配置即发版配置"立成规矩，云打包前的配置核对截屏留档。插件层的问题有个共同点：报错信息离真实原因很远，答案几乎都在配置与版本的对齐上。

插件与适配层的衔接规范

插件选进来了，最后一步是把它安放进第 6.2 节的适配层体系。规范两条：其一，requireNativePlugin 的调用只允许出现在 utils 适配层里，业务页面拿到的永远是语义化函数（readWeight、startScan），插件名与原生细节不外泄；其二，每个插件函数补一段"无插件端的行为"注释——抛错、降级还是静默，三选一写清楚，跨端调用方按注释处理。这两条执行到位，插件的可替换性就锁住了：某天换厂商或换 uts 自研，改动半径只有适配层一个文件。插件是能力，适配层是接口，能力常换接口常稳，这是原生插件工程的全部要义。

本节要点回顾

• 上插件前过三问：uni API 覆盖吗、降级可接受吗、维护成本养得起吗；
• 集成四步：选型三查、manifest 登记、自定义基座、双端真机验证；
• "插件不存在"类报错先查基座——标准基座没有插件，调试必须自定义基座；
• 插件生效点在云打包，热更补不了插件变更，发版清单要列明；
• uts 插件适合逻辑型能力自研，一份代码产出双端原生源码。

插件通道打通，下一节把散落的限制收进清单：小程序平台的边界与绕行。