Skip to content

uni-app x:原生渲染路线与 UTS ​

本篇要点:能分清 VDOM 与蒸汽两条路线的产物差异,判断项目该不该迁、要改哪四处,并写出一个能跑通的最小 UTS 插件。 前置文章:《原生能力:UTS 插件与原生插件开发》把原生能力封进了 UTS 插件;这一章看同一套 UTS 在 uni-app x 里究竟占哪一层。

为什么需要它 ​

2026 年 3 月,一个日活两万的电商 App 要做迁移。商品瀑布流快速滑动时掉帧,团队决定从 uni-app(Vue3)切到 uni-app x 的蒸汽模式,排期按「全站 uts 化」来做——每个页面的 script 都改成 uts,指望它编译成 Kotlin。

两周后发现方向错了:页面里的 uts 经 uts2js(把 uts 转成 js 的编译步骤)转成 js,仍然跑在 js 引擎上;真正编译成 Kotlin、Swift、ArkTS 的,只有 utssdk 目录里的插件代码。

这个判断错误很贵,因为它决定两件事:迁移的工作量怎么估,性能收益从哪来。蒸汽模式的快不来自语言,来自渲染引擎:template 和 style 被直接编译成字节码或机器码,页面驱动才交给 js。把 uts 写在页面里,付出的是类型约束的代价,拿到的是 js 引擎的执行结果。

截至 2026 年 11 月,uni-app x 内部并存两代:VDOM(Virtual DOM,虚拟 DOM)模式与蒸汽模式(vapor)。官方写明,2027 年初停止 uni-app 的 App 平台和 uni-app x VDOM 平台的维护;同一段话里还有一句「不再维护不是下线」,指没有重大兼容问题就不再更新。这句限定语值得记住:存量项目不会被强行掐断,但也拿不到新能力。

把判断落到项目上:新项目要三端齐发,蒸汽模式值得上;已经攒了一堆 uts 业务代码的项目别急着迁,先算清有多少页面 uts 会变成 js;还要覆盖 Android 5 的项目直接放弃这条线,最低版本抬不上去。

核心概念 ​

三条路线:产物落在哪一层 ​

三条路线各自的产物,如图 7-1 所示。

图 7-1 三条渲染路线的产物位置

「原生渲染」不等于「自渲染」。蒸汽模式并没有另开一块 surface(系统分配的绘图层)自己画,它复用的是系统分配给应用的画布、合成机制与 GPU 上下文,自己实现的是排版系统和组件系统——Android 有 View 体系、Compose UI 体系,它算第三套。自渲染方案常见的冷启动慢、与原生页面混排撕裂,来自「新开画布再并回大合成」这个动作,蒸汽模式没有这一步。

蒸汽模式还是分平台落地的:鸿蒙在 HBuilderX 5.0 先支持,iOS 5.11 跟上,Android 5.21 才落地。今年年初还有大量「Android 不支持蒸汽模式」的文章,那是时间差留下的化石。这张图也解释了为什么 Web 端的性能结论不能直接复用:Web 仍跑 VDOM,组件树与更新方式都不同。

UTS 的编译边界:只剩 utssdk 一层 ​

官方把规则压成三条:所有 UTS 插件都编译为原生语言;只有 App-Android 的 VDOM 页面里,页面 uts 才编成 Kotlin;蒸汽模式页面不能直接调原生 API,要调就封成插件,utsAndroid 在 uvue 页面下不可用。

平台老 uni-app 页面脚本x 的 VDOM 页面x 的蒸汽页面任意 UTS 插件
Web / 小程序JSJSJSJS
AndroidJSKotlinJSKotlin
iOSJSJSJSSwift
鸿蒙 NEXTJSJSJSArkTS

看着像能力收缩,实际是把「各平台原生 SDK 的差异」压进一个类型契约。接鸿蒙振动,写二十来行 uts 就通了;同样的能力在 Android 上手工接原生插件,两天。

代价在语言上。UTS 不是 TypeScript 的超集,类型系统按「能翻译成 Kotlin/Swift/ArkTS」设计:没有 undefined,可空只能写 T | null,用之前必须 ?. 或判空;number 是统一数字类型,不分 int 和 double,要平台特有能力就上条件编译;字面量推导从 4.31 起变强,但数字和数组仍建议显式标类型。

类型契约:先写 interface.uts ​

一个插件的最小结构是 interface.uts 定契约、各平台目录各实现。契约像报关单:字段、可选性、错误码先写清楚,各平台实现只是按单交货。多端一致性靠它约束——某个平台少实现一个字段,编译期就会暴露。反例是把类型散在各平台实现里,调用方在 iOS 上能编译,到 Android 才发现字段名不同。

性能数字的前提 ​

官方 4050 元素测试(同屏 2050 个 view 套 2000 个 text,不懒加载、不复用)的数字如下,Android 侧必须打 release 包,鸿蒙侧用 release 模式运行:

平台与设备原生蒸汽模式
Android 小米 Fold4原生 View 461.8ms,Compose 625.8ms229.2ms
iOS iPhone SE2UIKit 329.4ms158.2ms
鸿蒙 nova12(API 21)ArkUI 798ms280ms

官方 benchmark 页还附了非拍平版本的 276.2ms 作对照,用来单独看拍平贡献了多少。数字与前提可在官方蒸汽模式文档与三份 benchmark 报告里核。

长列表的差距更大:4000 行、7.4M JSON、两万个元素,Android 原生 View 平均 45.35 FPS、Compose 51.09,蒸汽 109;鸿蒙 ArkUI 21.13,蒸汽 97.97。数字能复现,但要带上前提:release 包、拍平只对 view/text/image、帧率绑屏幕刷新率、鸿蒙对比对象是 ArkUI 的 lazy foreach。漏掉任何一条,这组数字就能推出反向结论。

迁移的四处硬约束 ​

第一处,选项式 API。蒸汽模式只吃组合式(setup),不支持 export default { data() {} },也不支持 mixin。存量页面有多少个选项式,工作量就有多少。

第二处,CSS 子集。出于性能考虑只支持简单 class 选择器和分组选择器,.parent .child 这类后代选择器不生效,得换成 BEM(Block Element Modifier)的 .parent__child;scss 是编译期方案,不受影响。样式隔离只支持 2.0,组件默认 isolated,外部同名 class 打不进去,要 defineOptions({ styleIsolation: 'app' }) 才放开。

第三处,最低系统版本。蒸汽模式要求 Android 6+(默认 target 36,VDOM 是 Android 5 / target 32)、iOS 15+、鸿蒙 API 20(鸿蒙 6.0)。某个只适配 target 32 的老插件会在编译期直接报错,只能升插件或在 manifest 里降 target。

第四处,list-view 的复用规则:list-item 上的 v-for 必须有 :key;list-item 和 list-view 必须写在同一个 uvue 文件里;一个 list-view 下只有第一个带 :key 的 v-for 会复用,第二个起退化成普通 view。把列表项抽成独立组件,功能全对,滚动帧率掉一半,而且不报错、不打日志。

动手实践 ​

第一步:打开蒸汽模式,确认条件编译分支 ​

在 HBuilderX 5.21+ 打开项目,manifest.json 可视化界面首页勾选蒸汽模式,然后 Android 真机运行。用条件编译确认当前分支:

js
// pages/index/index.uvue 的 script 里
// #ifdef VUE3-VAPOR
console.log('[route] 蒸汽模式')
// #endif
// #ifndef VUE3-VAPOR
console.log('[route] VDOM 模式')
// #endif

运行结果:Android 真机日志打印 [route] 蒸汽模式;把 manifest 里的勾选去掉再运行,打印 [route] VDOM 模式。注意 Web 端即使开了蒸汽模式也按 VDOM 运行,小程序端没有蒸汽模式这个概念——这个开关只影响 App 三端。

第二步:写一个最小 UTS 插件 ​

先写契约:

uts
// uni_modules/uni-toast-demo/utssdk/interface.uts
export type ToastOptions = {
  title: string
  duration?: number
}

export type ShowToast = (options: ToastOptions) => void

运行结果:保存后,在页面里 import { showToast } from '@/uni_modules/uni-toast-demo',HBuilderX 的补全里出现 title 与 duration;把 title 写成 text 会直接标红,编译不通过。

再写 Android 实现:

uts
// uni_modules/uni-toast-demo/utssdk/app-android/index.uts
import Toast from 'android.widget.Toast'
import { UTSAndroid } from 'io.dcloud.uts'
import { ToastOptions, ShowToast } from '../interface.uts'

export const showToast: ShowToast = (options: ToastOptions): void => {
  const ctx = UTSAndroid.getAppContext()
  // LENGTH_SHORT = 0,LENGTH_LONG = 1;2000ms 是系统给的分界
  const flag = (options.duration ?? 2000) > 2000 ? Toast.LENGTH_LONG : Toast.LENGTH_SHORT
  Toast.makeText(ctx, options.title, flag).show()
}

运行结果:自定义基座里点按钮,屏幕底部弹出「已加入购物车」,2 秒后消失;传 duration: 3000 变成系统长 Toast,约 3.5 秒,时长由 LENGTH_LONG 决定,不按传入值走。用标准基座运行会报找不到插件——插件代码没有编进基座,原因见《原生能力:UTS 插件与原生插件开发》。

第三步:跑一遍迁移体检 ​

迁移前先用脚本数一遍存量代码里有多少处会挡路:

js
// scripts/vapor-check.mjs —— 在项目根目录执行 node scripts/vapor-check.mjs
import { readdirSync, readFileSync, statSync } from 'node:fs'
import { join } from 'node:path'

const rules = [
  { name: '选项式 API', re: /export\s+default\s*\{[\s\S]*?data\s*\(/ },
  { name: 'mixin', re: /\bmixins\s*:/ },
  { name: '后代选择器', re: /^\s*\.[\w-]+\s+\.[\w-]+\s*\{/m },
]

function walk(dir, out = []) {
  for (const name of readdirSync(dir)) {
    const p = join(dir, name)
    if (statSync(p).isDirectory()) walk(p, out)
    else if (/\.(uvue|vue)$/.test(name)) out.push(p)
  }
  return out
}

const files = walk('pages')
const hits = rules.map((r) => ({
  rule: r.name,
  files: files.filter((f) => r.re.test(readFileSync(f, 'utf8'))).length,
}))
console.table(hits)

运行结果:终端打印一张三行表,列是规则名与命中文件数。这三个数字是改造工作量的下限,不含手工回归。若扫出来是 41、6、23,先改 41 个选项式页面,再动样式;顺序反了会把同一批页面改两遍。脚本只做静态扫描,正则匹配不到动态拼出来的 class 名,也覆盖不到间接引用;它给出的是量级,不是精确清单。

第四步:给热更新加一道版本锁 ​

5.31 起 Android 与 iOS 支持 wgt(资源热更新包)热更新,但引入了 compilerRuleVersion 校验:HBuilderX 5.32+ 该值为 1,5.36+ 为 2;字节码资源必须与应用基座完全一致,否则 uni.installWgt 直接装不上。灰度之前先确认基座和 wgt 出自同一个 HBuilderX 版本,这条在文档末尾,篇幅很短,却是灰度事故的常见成因。

常见误解 ​

其一,以为页面里写 uts 就能拿到原生性能。蒸汽模式页面的 script 支持 js/ts/uts,但除 App-Android 的 VDOM 模式外,页面 uts 一律编成 js。快的是渲染引擎,不是语言。

其二,以为官方 benchmark 的数字可以直接搬到自己项目。那台 iPhone SE2 最高 60Hz,小米 Fold4 和鸿蒙机是 120Hz,拿 60Hz 的帧率横比 120Hz 的帧率就是错的;拍平只对 view、text、image 三个组件生效,video 走 ExoPlayer、map 走原生 SDK,与原生持平,只有高频且有压力的组件被专项优化过。数字是特定测试例的结果,不是产品承诺,自己项目还得用自己的页面结构测。

其三,以为「2027 年停止维护」等于下线,可以按自己的节奏慢慢迁。官方原文是「不再维护不是下线」,但 Web 端目前仍以 VDOM 模式跑蒸汽模式的代码,小程序端没有蒸汽模式。这个开关只影响 App 三端,「同一个组件在三个平台表现一致」的假设只在 App 上成立,Web 的性能假设要单独验。

其四,以为 CSS 只是「少几个选择器」。后代选择器不生效,会让写惯 Web 的人第一小时就卡住;样式隔离 2.0 下外部 class 默认打不进组件,改主题时会遇到「样式写了但没生效」;list-item 包一层组件复用就失效,这条最不讲道理,因为功能全对。

小结 ​

《原生能力:UTS 插件与原生插件开发》把 UTS 用来封原生能力,这一章说明它在 uni-app x 里的边界比想象中窄。五条要点:

  • 三条路线产物不同:WebView、原生组件树加虚拟 DOM、原生渲染引擎加字节码。2027 年初 uni-app 的 App 平台与 x 的 VDOM 平台停止维护,「不再维护不是下线」。
  • UTS 的编译边界只剩 utssdk:插件编 Kotlin/Swift/ArkTS,页面 uts 在蒸汽模式下编 js,页面不能直接调原生 API。
  • 性能数字全部带前提:release 包、拍平只对 view/text/image、帧率绑刷新率、鸿蒙对比 ArkUI lazy foreach。
  • 迁移四处硬约束:组合式 API、CSS 子集与样式隔离 2.0、最低系统版本、list-view 复用规则。
  • wgt 热更新有 compilerRuleVersion 锁,基座与 wgt 必须同源,否则灰度装不上。

相关主题 ​

路线和渲染都定了,下一个问题是钱怎么收。[《支付与交易:多端支付集成与对账》](/guide/uniapp/uniapp-payment.html)从统一下单讲到回调验签,把这套多端项目接上微信支付与支付宝。