原生能力: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.android | JS 运行时反射调用原生类 | 无 | 仅 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 才用 |
| iOS | CocoaPods(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 就要重新打一次基座,一次几分钟。
所以「改完配置直接点运行,看到的还是旧行为」是最耗时间的假故障:原生配置被编进了基座产物,你的改动在基座里不存在。排查时先看基座构建时间,再看日志,比翻代码快。
动手实践
第一步:先写契约
// 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 实现
// 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
{
"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 一起集成。
第五步:在页面里调用
// 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 驱动。