uni-app uts原生插件开发:uts 与 Kotlin 交互踩坑实录(附解决方案)

前言

在 uni-app 中开发 Android 原生插件(UTS 插件),最容易出问题的不是 Android 本身,而是 UTS 语言与 Kotlin 之间的交互层。本文基于一个真实保活插件项目,把开发中实际踩到的坑整理出来,每个问题都附带报错信息和可直接复用的解决方案。

一、类型转换:最高频的报错区

坑 1:number 不能直接赋值给 Kotlin 的 Int/Long

报错信息:

go 复制代码
error: Assignment type mismatch: actual type is 'Number', but 'Int' was expected.
at index.uts:172:30

原因: UTS 的 number 对应 Kotlin 的盒装 Number,不会自动拆箱转换。

解决: 显式调用转换方法。

ts 复制代码
// Kotlin 端
var alarmType: Int = 1
var alarmPeriodMs: Long = 0L

// UTS 端(错误写法)
VibrateConfig.alarmType = type              // 编译报错
VibrateConfig.alarmPeriodMs = periodMs      // 编译报错

// UTS 端(正确写法)
VibrateConfig.alarmType = type.toInt()
VibrateConfig.alarmPeriodMs = periodMs.toLong()

记忆口诀:Int 用 .toInt(),Long 用 .toLong(),Float 用 .toFloat(),一个都不能省。

坑 2:空值不能直接传给非空类型

Kotlin 是空安全语言,UTS 传过去的 null 会直接导致编译失败或运行时崩溃。

标准兜底写法:

ts 复制代码
const opt: XxxOptions = options == null ? ({} as XxxOptions) : options
const periodMs: number = opt.periodMs == null ? 900000 : opt.periodMs!

! 非空断言是 UTS 对接 Kotlin 空安全的标准动作,项目中会大量使用。

坑 3:UTS 接口对象和 Kotlin 类不能混用

UTS 的 type 定义只是数据契约,返回时必须重新构建对象,不能把 Kotlin 类直接当 UTS 类型返回。

推荐做法:Kotlin 内部类和 UTS 接口刻意不同名,UTS 层逐字段搬运。

ts 复制代码
// UTS 接口
export type VibratePermResult = {
  success: boolean
  granted: boolean
  message: string
}

// Kotlin 内部类叫 VibratePermOutcome(不同名,避免类重声明冲突)
// UTS 层重建为接口对象
function toPermResult(success: boolean, granted: boolean, message: string): VibratePermResult {
  return {
    success: success,
    granted: granted,
    message: message
  } as VibratePermResult
}

二、语法代际:选错语法,错误非常隐蔽

uni-app 分两代工程,可选字段的语法完全不同:

ts 复制代码
// 传统 uni-app(vue2/vue3)------ 本项目使用
duration ?: number

// uni-app x(uvue)
duration?: number

最坑的点: 用错语法不会立即报错,而是生成错误的继承类,直到 Kotlin 编译阶段才炸,极难定位。

判断方法: 打开插件的 package.json,看到 vue2: "√" 就是旧语法工程,必须用 字段 ?: 类型。

三、Kotlin 类的引用规则

规则 1:同包 Kotlin 类直接用类名,禁止 import .kt 文件

ts 复制代码
// 正确
VibrateApp.init(context)
VibrateConfig.persistentKeepAlive = true

// 错误:uts-loader 解析不了 .kt 模块
import { VibrateApp } from './VibrateApp.kt'

规则 2:启动 Service/Activity 用反射拿 Class

ts 复制代码
const serviceClass = Class.forName("uts.sdk.modules.fengyuVibrate.VibrateForegroundService")
const intent = new Intent(context, serviceClass)
context.startForegroundService(intent)

而访问常量、单例方法直接类名点出来即可:

ts 复制代码
intent.setAction(VibrateForegroundService.ACTION_ENTER_FOREGROUND)
VibrateAlarmScheduler.schedule(context, delay)

规则 3:给 UTS 调用的伴生方法必须加 @JvmStatic

kotlin 复制代码
companion object {
    @JvmStatic          // 不加 UTS 侧找不到符号
    fun schedule(context: Context) { ... }
}

另外,Kotlin 中 private set 的属性 UTS 只能读不能写,写操作要走专门的方法:

kotlin 复制代码
var foregroundActive: Boolean = false
    private set
fun markForegroundEnter() { foregroundActive = true }

四、回调跨边界:进程死了,回调就没了

回调的存放方式

Kotlin 侧声明可空函数类型,UTS 直接赋值:

kotlin 复制代码
object VibrateCallbackBridge {
    @Volatile
    var alarmCallback: (() -> Unit)? = null
}
ts 复制代码
VibrateCallbackBridge.alarmCallback = opt.onFire   // 注册
VibrateCallbackBridge.alarmCallback = null         // 注销

关键认知:回调不保证送达

当 App 进程被系统杀死后,闹钟/WorkManager 唤醒的是全新进程,JS 引擎根本没有初始化,回调必然丢失。

所以架构设计上要遵守一条铁律:

必须执行的逻辑放在原生动作(拉服务、发通知)里,JS 回调只做进程存活时的界面刷新,不能承担业务承诺。

原生侧分发回调也要切到主线程:

kotlin 复制代码
Handler(Looper.getMainLooper()).post {
    try { cb.invoke() } catch (e: Exception) { e.printStackTrace() }
}

五、状态持久化:单例在新进程里会归零

这是整个项目最核心的教训。

问题场景

Kotlin 的 object 单例是内存态,进程被杀后重建,所有字段恢复默认值:

kotlin 复制代码
object VibrateConfig {
    var persistentKeepAlive: Boolean = false  // 新进程里永远是 false
}

结果:WorkManager 15 分钟后唤醒 Worker,读到 false,直接不拉活服务,保活形同虚设。

解决方案:getter/setter 代理 SharedPreferences

kotlin 复制代码
var persistentKeepAlive: Boolean = false
    get() = sp()?.getBoolean(KEY_PERSISTENT, false) ?: field
    set(value) {
        field = value
        sp()?.edit()?.putBoolean(KEY_PERSISTENT, value)?.apply()
    }

private fun sp() = appContext?.getSharedPreferences("cfg", Context.MODE_PRIVATE)

Context 的挂载要做成幂等双路初始化(UTS 首次调用 + Service/Receiver 的 onCreate 都会调一次):

kotlin 复制代码
fun init(context: Context) {
    if (appContext == null) {
        appContext = context.applicationContext
        VibrateConfig.attachContext(context)
    }
}

设计时每个开关字段都问自己一句:进程被杀重建后,这个值还读得到吗?

六、Android 版本兼容:低版本手机的隐形炸弹

坑 1:高版本 API 符号在低版本运行时崩溃

直接引用高版本常量,在低版本系统上会抛 NoClassDefFoundError。

统一手法:数值字面量 + SDK 版本判断。

kotlin 复制代码
// 不要直接写 ServiceInfo.FOREGROUND_SERVICE_TYPE_SPECIAL_USE(API34 才有)
private const val FGS_TYPE_SPECIAL_USE = 1 shl 30   // 字面量替代

val type = if (Build.VERSION.SDK_INT >= 34) {
    FGS_TYPE_SPECIAL_USE
} else {
    1 shl 1   // mediaPlayback
}

坑 2:minSdk 决定每个 API 都要查引入版本

本插件 minSdk = 21,而 setExactAndAllowWhileIdle() 是 API23 才有的方法,直接调用在 Android 5.0 上必崩:

kotlin 复制代码
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    am.setExactAndAllowWhileIdle(...)   // API23+
} else {
    am.setExact(...)                    // API21/22 无 Doze,效果等价
}

坑 3:后台启动前台服务的两类异常

Android 12+ 后台直接 startForegroundService() 会遇到:

异常 触发条件 处理方式
ForegroundServiceStartNotAllowedException 后台身份不允许启 FGS 可显式 catch
ForegroundServiceDidNotStartInTimeException 5 秒内没调到 startForeground hidden 类,用 catch(Exception) 兜底

正规解法:Worker 中先 setForeground() 让 WorkManager 托管提权,再启动自己的服务。

kotlin 复制代码
class XxxWorker(context: Context, params: WorkerParameters) : CoroutineWorker(context, params) {
    override suspend fun doWork(): Result {
        // 1. 先拿合法前台身份
        setForeground(ForegroundInfo(noticeId, notification, fgsType))
        // 2. 前台窗口内再启业务服务
        val ok = XxxServiceLauncher.ensureForegroundService(applicationContext)
        return if (ok) Result.success() else Result.retry()
    }
}

七、依赖与编译排错经验

1. WorkManager 版本坑

  • ExistingWorkPolicy.APPEND_OR_REPLACE 是 2.9.0 才有 的枚举,2.8.1 编译直接找不到符号,低版本用 REPLACE 替代
  • 用 CoroutineWorker 和 setForeground 需要依赖 work-runtime-ktx,不是 work-runtime
  • 不用 ktx 时不能用 workDataOf(),改用 Data.Builder().putBoolean(k, v).build()

2. 什么时候必须重新打自定义基座

改动内容 热同步 重打基座
页面 .vue / 业务 .uts 逻辑 可以 不需要
新增/升级 config.json 依赖 不行 必须
修改 AndroidManifest / 权限 不行 必须
新增 .kt 文件 不行 必须

拿着旧基座反复热同步排查新代码,是纯浪费时间。

3. 报错日志怎么看

控制台只显示 kotlin编译失败 加一堆 node 堆栈时,往上滚动,真正的原因格式是:

go 复制代码
error: 具体原因 at 文件:行号:列号

4. UTS 层异常捕获不能带类型注解

ts 复制代码
// 正确
try { } catch (e) { }

// 错误:这是 Kotlin 语法
try { } catch (e: Exception) { }

八、总结:一条分层原则

整个项目踩完坑后,总结出 UTS 插件的分层铁律:

UTS 层只做翻译工:类型转换、空值兜底、参数校验; 状态持久化、集合操作、反射、线程切换、系统 API 细节全部下沉到 Kotlin 层。

最后附上开发自测 Checklist:

  • 所有 number 传原生都显式 .toInt()/.toLong()
  • 可选字段语法与工程代际匹配(vue2 用 ?:)
  • 给 UTS 调的 companion 方法都加了 @JvmStatic
  • 开关类状态全部落 SharedPreferences,经得住进程重建
  • 每个系统 API 都查了引入版本,低版本有分支
  • 业务承诺不依赖 JS 回调
  • 改了依赖/Manifest/kt 文件后重打基座,不做无效热同步

希望这些实战经验能帮你少走弯路。

相关推荐
再吃一根胡萝卜27 分钟前
DSH 插件数据链路:Host 管数据,Client 只管画
前端
feixing_fx32 分钟前
CSS 变量(Custom Properties):构建可扩展的主题切换系统
前端·css·前端框架·html·css3
AndreaYYmm37 分钟前
手动敲能跑,cron 一跑就 command not found?聊聊 PATH 到底从哪来
后端
bcbnb1 小时前
Windows 上 iOS 开发接 CI,KXBuild 自托管 runner 出签名 ipa
后端·ios
十有八七2 小时前
手搓 Agent(一):先有大脑——大模型只会做一件事
前端·人工智能·后端
锋行天下2 小时前
「踩坑实录」给 LangGraph Agent 接两个 FastMCP,我被 langchain 偷偷改了工具名
前端·人工智能·后端
Resean02232 小时前
Spring 源码分析(一)IOC 容器总览与 refresh() 全景
java·后端·spring
苍何2 小时前
一句话出成片,我搭了个AI视频工厂
后端
跳跳的小星星2 小时前
自研组件】Vue2 + ElementUI 通用列表页封装 wkjp-list-page,一套配置搞定搜索、动态表格、分页、增删改
前端