Skip to content

原生能力:UTS 插件与原生插件开发 ​

本篇要点:能用 interface.uts 先定契约,给 Android、iOS、鸿蒙各写一份实现,在自定义基座里跑通一次插件调用,并看懂「改完配置没生效」这类假故障。 前置文章:《性能优化:setData、长列表与首屏加载》把页面性能压到了可接受的范围;这一章要碰的是页面之外的能力——扫描、蓝牙、厂商 SDK。

为什么需要它 ​

2025 年底,一个「读取已安装应用列表并跳转」的插件交给外包写。核心方法十几行,提审被驳回三次:第一次没有声明包可见性,Android 11+ 上 getPackageInfo 永远返回不存在;第二次 iOS 缺隐私清单;第三次鸿蒙侧权限声明缺失。三次都不是代码逻辑错误,而是三个平台各有各的前置声明,且这些声明与代码分居不同目录。

这类需求在业务里出现得很频繁:扫一扫要相机权限,推送要厂商通道,地图要原生 SDK。四条技术路线并存——Native.js、原生插件、UTS 插件、内置 API——选错一条,后面全是返工。

UTS 是 uni type script 的缩写,一种能编译成 Kotlin、Swift、ArkTS 等目标语言的类型化脚本。截至 2026 年 11 月,UTS 插件在 HBuilderX 3.6+ 的 uni-app 项目和 3.9+ 的 uni-app x 项目中都能用,编译目标覆盖 Kotlin、Swift、ArkTS 与 JavaScript。这一章按「选型、契约、实现、依赖、调试」的顺序走一遍,最后讲几个不报错的坑。

核心概念 ​

四代方案的分界线在运行模型 ​

方案原理类型安全多端复用适用场景
Native.js / plus.androidJS 运行时反射调用原生类无仅 App临时验证、极小功能
原生插件手写原生代码,经 JSBridge 暴露弱(JSON 传参)各端各写一份大型 SDK、需要原生 UI
UTS 插件UTS 编译为 Kotlin / Swift / ArkTS强(编译期检查)一份代码多端绝大多数扩展需求
uni-app x 内置 API官方已封装强多端通用能力优先用内置

分界线不是新旧,是运行模型。Native.js 靠反射在运行时找方法,拼错方法名要到真机执行时才崩;原生插件靠 JSBridge(JS 与原生之间的通信桥)传 JSON,参数类型在桥上丢失;UTS 插件在编译期翻译成目标平台的原生代码,写错方法名编译就报错。类比:反射是到了现场才问「这里有没有这个门」,编译期翻译是出发前就拿到门禁卡。

反例是拿 Native.js 去写长期维护的模块。它能省下当天的配置时间,代价是每次系统升级、每个机型差异都变成线上崩溃,而且没有类型提示。

编译期翻译:产物是原生二进制 ​

一次编译的产物走向,如图 6-1 所示。

图 6-1 UTS 插件的编译目标与产物

关键在「编译期翻译」四个字。它不是解释执行,也不是运行时反射找方法,而是被编译成目标平台的原生代码。所以没有 JSBridge 的序列化开销,写错方法名编译就报错,而不是等某台线上设备崩溃。

这也解释了 UTS 最重要的约束:它不是 TypeScript 的超集。语法接近,但类型系统是按「能翻译成 Kotlin/Swift/ArkTS」设计的,动态属性、any 滥用、宽泛的泛型与重载都不支持。写的时候要一直想着「这行翻成 Kotlin 长什么样」。

interface.uts 与 index.uts 的分工 ​

一个 UTS 插件本质上是一个 uni_modules(uni-app 的插件目录规范)包,核心目录如图 6-2 所示。

图 6-2 一个 UTS 插件的目录结构

官方推荐把对外类型全部写在 interface.uts,各平台目录下的 index.uts 只做实现。这不是形式主义:HBuilderX 靠它给调用方语法提示,多端一致性也靠它约束——契约写死之后,某个平台少实现一个字段,编译期就能发现。

原生依赖怎么进来:优先仓储坐标 ​

先给结论:能用仓储坐标就别塞本地库。

平台方式写法建议
Android仓储依赖config.json 的 dependencies 写 implementation 坐标有 Maven 坐标时优先
Android本地库丢进 app-android/libs/(jar / aar / so)只有私有 SDK 才用
iOSCocoaPods(iOS 依赖管理)config.json 的 dependencies-pods(3.8.5+)大多数三方 SDK 的首选
iOS手动集成Frameworks/、Libs/Pod 不可用时才用
鸿蒙HAR(Harmony Archive)放 app-harmony/ 按 ArkTS 规范引用复杂 SDK 建议先验证

同样的坐标写错,在不同阶段报错:写进 plugins 白名单外的插件是构建期静默不加,写错 so(动态链接库)的 abi(CPU 架构)是运行期 UnsatisfiedLinkError。project.plugins 是白名单机制,目前只放行 com.google.gms.google-services、com.huawei.agconnect、com.hihonor.mcs.asplugin 三个;repositories 需要 HBuilderX 4.36+。iOS 侧的关键参数是 deploymentTarget,默认 12.0,规则是取所有依赖最低支持版本里最高的那个,设低了打包失败,设高了丢老用户;validArchitectures 默认只有 arm64。

自定义基座是唯一的门 ​

UTS 插件的调试流程和普通业务代码完全不同。Android 的原生配置(依赖、Manifest、资源)只有经过云端打包才生效,标准 HBuilderX 基座里根本没有你的 SDK。改一次 config.json 就要重新打一次基座,一次几分钟。

所以「改完配置直接点运行,看到的还是旧行为」是最耗时间的假故障:原生配置被编进了基座产物,你的改动在基座里不存在。排查时先看基座构建时间,再看日志,比翻代码快。

动手实践 ​

第一步:先写契约 ​

uts
// uni_modules/uni-app-installed/utssdk/interface.uts
export type IsAppInstalledOptions = {
  packageName: string
  success?: (res: IsAppInstalledResult) => void
  fail?: (err: IsAppInstalledFail) => void
}

export type IsAppInstalledResult = { installed: boolean }

// 错误码沿用 uni 错误规范,90 开头避免与系统码冲突
export type IsAppInstalledErrorCode = 9010001 | 9010002

export interface IsAppInstalledFail extends IUniError {
  errCode: IsAppInstalledErrorCode
}

export type IsAppInstalled = (options: IsAppInstalledOptions) => void

运行结果:调用方 import { isAppInstalled } 后,options 的补全里只有 packageName、success、fail 三个字段;把 packageName 拼成 packageNmae 会编译报错,而不是在真机上静默拿到 undefined。

第二步:写 Android 实现 ​

uts
// uni_modules/uni-app-installed/utssdk/app-android/index.uts
// 预期输出:目标应用已安装 -> success({ installed: true })
import { IsAppInstalledOptions, IsAppInstalledResult, IsAppInstalled } from '../interface.uts'
import { IsAppInstalledFailImpl } from '../unierror'

export const isAppInstalled: IsAppInstalled = function (options: IsAppInstalledOptions) {
  const context = UTSAndroid.getAppContext()
  if (context == null) {
    // 上下文为空通常意味着插件在非 UI 进程被调用,属于集成错误
    options.fail?.(new IsAppInstalledFailImpl(9010002))
    return
  }
  let installed = false
  try {
    context.getPackageManager().getPackageInfo(options.packageName, 0)
    installed = true
  } catch (e) {
    installed = false // 包不存在抛 NameNotFoundException,是正常分支
  }
  const res: IsAppInstalledResult = { installed }
  options.success?.(res)
}

运行结果:目标应用已安装时回调 success({ installed: true });未安装时 success({ installed: false }),不抛异常;上下文为空时 fail 收到 errCode: 9010002。原生异常被翻译成 UTS 错误码,调用方拿到的不是一坨 Kotlin 堆栈。

每一端都要有 index.uts,哪怕是空实现。缺文件不是「该端不支持」,而是编译直接失败——这是新手最常见的第一个报错来源。

第三步:把依赖和架构写进 config.json ​

json
{
  "minSdkVersion": 21,
  "abis": ["arm64-v8a", "armeabi-v7a"],
  "dependencies": [
    "androidx.core:core-ktx:1.12.0",
    {
      "id": "com.example.sdk:core",
      "source": "implementation 'com.example.sdk:core:3.2.1'"
    }
  ],
  "project": {
    "plugins": ["com.huawei.agconnect"],
    "repositories": ["maven { url 'https://developer.huawei.com/repo/' }"]
  }
}

运行结果:云打包日志里能看到 com.example.sdk:core:3.2.1 参与依赖解析,打出的 apk 能解出对应 so;把 abis 里的 armeabi-v7a 删掉后包体积下降约三分之一,但 32 位老设备装上直接提示不兼容。minSdkVersion 在 uni-app x 项目里最低 21。

第四步:打自定义基座,真机跑通 ​

运行 → 运行到手机或模拟器 → 制作自定义调试基座,等云端打包完成,再用自定义基座运行。运行结果:标准基座下调用报插件不存在或方法未定义;换成自定义基座后,isAppInstalled 的回调正常返回,不再报插件不存在。Android 侧还不支持直接用 so 调试,必须把 so 和调用代码封成 AAR(Android 归档库),或者 jar 与 so 一起集成。

第五步:在页面里调用 ​

js
// pages/index/index.vue
import { isAppInstalled } from '@/uni_modules/uni-app-installed'

isAppInstalled({
  packageName: 'com.tencent.mm',
  success: (res) => console.log('[plugin] installed', res.installed),
  fail: (err) => console.warn('[plugin] fail', err.errCode)
})

运行结果:装了微信的真机打印 [plugin] installed true;换成没装的包名打印 false。Android 11+ 上没有在 AndroidManifest.xml 里声明 <queries> 时,即使应用真的装了也会返回 false——平台策略导致的假阴性,UTS 不会帮你兜住。

常见误解 ​

其一,以为 UTS 的 any 和 TS 的 any 一样好用。它在翻译成 Kotlin/Swift 时会退化,边界处传对象进去,另一端可能拿到 Object 而不是具体类型。这类问题不报错,表现为运行时类型错。

其二,以为 abis 砍掉 32 位一定安全。只发 64 位能省将近一半体积,但部分低端机和定制 ROM 还在 32 位上,砍掉会直接装不上。要看真实设备分布再决定,不是看趋势。

其三,以为插件越多能力越强。uni-app x 的模块是摇树打包的,用了才进包;自己封一个与内置 API 功能重叠的插件,等于白加体积。体积这块有个真实数字:接进来的 SDK 说 6MB,包胖了 22MB,多出来的是三份 abi 加一份没被调用的 x86_64,删掉之后什么都没坏,因为线上本来就没有 x86 手机。

其四,以为配置改完没生效是代码写错了。原生配置被编进基座,基座没重打,改动就不存在。把「打基座」放进流程,比写十条规范有用,因为忘了打的人五分钟内就会自己发现。

还有三个选型判断,值得在动手前先过一遍。能放服务端的能力别做成端插件:一个 20MB 的 OCR(光学字符识别)SDK 塞进包里,换来的是下载转化率下降,而识别如果能接受 300ms 网络延迟,放云函数更划算。稳定运行两三年的原生插件别做 UTS 迁移:迁移收益来自跟着 SDK 版本迭代,插件几乎不改,收益接近零;还在迭代的,通常第三个版本能收回成本。API 插件别用来做嵌在页面里的界面:API 插件操作界面只能是全屏窗口或弹窗,要嵌进 template 必须写组件插件,成本高一个量级。选之前先问一句:这个界面能不能用 Vue 画?

小结 ​

《性能优化:setData、长列表与首屏加载》把页面压快,这一章把页面伸到系统里。五条要点:

  • 四条路线的分界在运行模型:反射、JSBridge、编译期翻译、官方内置。长期维护的模块优先 UTS 或内置 API。
  • UTS 不是 TypeScript 超集,类型系统按目标语言设计;先写 interface.uts,再写各端 index.uts。
  • 依赖优先仓储坐标,iOS 注意 deploymentTarget 取依赖的最高值,Android 注意 plugins 白名单与 abis。
  • 原生配置只有云打包进基座才生效,改一次配置打一次基座;缺一端 index.uts 是编译失败,不是降级。
  • 几个不报错的坑:any 退化、砍 32 位、重复插件;包体积上线前后各打一次包对比。UTS 插件只能通过 HBuilderX 创建和使用,不支持纯 cli 工程,CI 只能调 HBuilderX 的 cli 做云打包。

相关主题 ​

插件能跑了,但页面渲染仍在 WebView 里。[《uni-app x:原生渲染路线与 UTS》](/guide/uniapp/uni-app-x-uts.html)看 uni-app x 的原生渲染路线:同一套 UTS 在那边只剩插件一层,页面脚本改由 js 驱动。