
前言
在 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 文件后重打基座,不做无效热同步
希望这些实战经验能帮你少走弯路。