基于 Kotlin MultiPlatform 的鸿蒙原生跨端实践：Kuikly 在 HarmonyOS NEXT 上的架构与接入思路

摘要：本文从鸿蒙原生应用开发痛点出发，介绍 Kuikly 基于 KMP 在 HarmonyOS NEXT 上的渲染架构、工程形态、性能特征与渐进式接入路径，提供落地参考。

1. 背景：鸿蒙适配不是"多一个端"，而是重构多端研发模型

随着 HarmonyOS NEXT 推进，很多团队面临三类问题：

代码资产难复用：Android / iOS 已有大量 Kotlin / 原生业务代码，鸿蒙若用 ArkTS 重写，人力与维护成本陡增。
跨端方案要原生感：WebView、JS Bridge、自绘引擎在启动速度、输入法、滚动手感、系统组件一致性上，和"鸿蒙原生应用"存在差距。
动态化与发版效率要求变高：运营页、活动页、AB 实验希望不发版更新，但又不能牺牲系统级体验。

在这种背景下，跨端框架的关键问题不再是"能不能跑"，而是：

能否在鸿蒙上以原生渲染路径运行，同时复用 Kotlin 多平台代码？

Kuikly 给出的答案是：KMP 编译到鸿蒙原生产物 + ArkUI Native / C-API 渲染 + 页面级动态化。

2. Kuikly 是什么：KMP 上的 UI 与逻辑跨端方案

Kuikly 是腾讯推出的基于 Kotlin Multiplatform 的跨端 UI 框架，使用 Kotlin 编写业务与 UI 描述，支持：

Android：编译为 .aar，映射原生 View
iOS：编译为 .framework / .xcframework，映射 UIView
HarmonyOS：编译为原生二进制 / .so，通过 ArkUI Native 接口渲染
Web / 小程序：Beta，复用跨端组件能力
macOS：Alpha 阶段

整体分层可概括为：

复制代码

Kotlin 共享层（commonMain）
  ├─ 业务逻辑
  ├─ 状态管理
  ├─ 布局计算 / 组件树
  └─ 跨端 API 抽象
        ↓ 编译 / 渲染指令
Native 渲染层
  ├─ Android  : Android View System
  ├─ iOS      : UIView / UIKit
  └─ HarmonyOS: ArkUI Native / C-API

核心特征有三：

语言闭环：Kotlin 写多端，Android 团队迁移成本最低。
原生渲染：高阶组件跨端，原子组件走平台原生控件。
可动态化：Core 与 Render 层通过指令通信，支持页面级下发更新。

3. 鸿蒙端关键技术：为什么是 ArkUI Native / C-API

鸿蒙 ArkUI 同时提供：

声明式 ArkTS 开发模型
命令式 ArkUI C-API / Native 接口

Kuikly 在鸿蒙上选择命令式原生接口渲染，原因是：

3.1 与 Kotlin/Native 调用链更短

Kuikly 的跨端层运行在 Kotlin/Native 侧，UI 描述最终转为"创建节点 / 设置属性 / 插入子节点 / 移除节点"等原子指令。

通过 ArkUI C-API 直接操作原生节点，可以避免"ArkTS 声明式树 ↔ 跨端命令式模型"的二次转换开销。

3.2 长列表与复杂 Feed 更稳

信息流、评论区、搜索结果页等场景对 Diff、复用、滚动帧率敏感。

Kuikly 在跨端层统一做组件树与布局计算，鸿蒙原生层只负责执行渲染指令，有利于：

减少 ArkTS 侧状态重算
降低节点重建频率
保持滚动惯性、键盘、安全区等系统行为一致

3.3 原生能力不丢

输入框、滚动容器、图片、手势、路由、权限、系统字体、暗色模式等，尽量走鸿蒙系统能力，而不是框架自己模拟。

这也是 Kuikly 与"WebView 方案""JS Bridge 方案""自绘引擎方案"的本质差异。

4. 鸿蒙工程中的典型架构

在一个 HarmonyOS NEXT 工程中，Kuikly 通常以混合开发方式存在：

复制代码

entry（ArkTS / DevEco 工程）
  ├─ 原生 ArkTS 页面
  ├─ Kuikly 容器页面（ArkTS 承载 Kuikly 实例）
  └─ NAPI / C++ 层
        └─ libkuikly.so / Kuikly Runtime
              └─ Kotlin/Native 业务与 UI 逻辑

shared（Kotlin Multiplatform）
  ├─ commonMain
  ├─ androidMain
  ├─ iosMain
  └─ ohosMain（鸿蒙特有适配）

接入时一般包含：

宿主鸿蒙工程引入 Kuikly 渲染库；
通过 NAPI 初始化 Kuikly Runtime；
ArkTS 页面创建 Kuikly 容器；
Kotlin 层注册 Page / Module / API；
原生 ArkTS 与 Kuikly 页面互相跳转、传参、调用系统能力。

5. 性能特征：不是"像原生"，而是走原生渲染路径

官方与业务落地中的典型结论：

鸿蒙 Render 基于 C 层 API 渲染，启动场景性能较早期方案有明显提升；
复杂 Feed 流场景下，Kuikly 鸿蒙版页面打开速度接近原生，显著优于 RN 鸿蒙适配方案；
无 JS 引擎、无额外虚拟机，包体积增量可控；
Android / iOS / 鸿蒙三端可用同一套 Kotlin 业务代码，减少三端逻辑分叉。

需要注意：

"原生渲染"不等于"所有系统差异消失"。字体、圆角、安全区、滚动回弹、输入法面板、权限模型仍需要按鸿蒙规范处理。

6. 适合鸿蒙项目的落地路径

阶段一：试点页面

适合：

设置页
关于页
活动页
个人中心
简单表单页

目标：验证构建链路、调试链路、路由跳转、埋点上报。

阶段二：列表型业务页

适合：

资讯列表
搜索结果
评论列表
商品信息流

目标：验证长列表性能、图片加载、下拉刷新、分页、骨架屏。

阶段三：复杂业务与动态化

适合：

运营活动
AB 实验
临时样式 / 逻辑修复
多端同步发版

目标：配合动态化通道做页面级下发，降低发版依赖。

阶段四：原生与跨端共存

存量 ArkTS 页面保留
新页面优先 Kuikly
系统级、强原生、强设备能力页面继续用 ArkTS

7. 什么场景适合，什么场景要谨慎

✅ 适合

已有 Android / Kotlin 团队
需要 Android + iOS + HarmonyOS 三端复用
对启动速度、滚动性能、包体积敏感
有运营动态化诉求
不希望用 ArkTS 完全重写业务

⚠️ 谨慎

强 3D / 粒子 / 自绘游戏
深度依赖前端 npm 生态
鸿蒙独有分布式硬件能力作为核心交互
把 Kuikly 当成"零成本完全一致"的银弹

8. 工程建议

共享层只放稳定逻辑：网络、模型、状态、路由协议、业务规则。
平台层只处理差异：权限、分享、推送、系统 UI、设备能力。
鸿蒙特有代码进 ohosMain：不要为了"完全统一"把系统差异藏进公共层。
原生页面与 Kuikly 页面边界清晰：用路由协议解耦，避免互相持有实现细节。
性能看真机：鸿蒙模拟器、x86 环境不能完全代表 ARM64 设备表现。

9. 小结

Kuikly 在鸿蒙上的价值，不在于"又多一个跨端框架"，而在于它把鸿蒙放到了 KMP 的一等 target 位置：

Kotlin 写业务与 UI → Kotlin/Native 编译 → ArkUI Native / C-API 渲染 → 鸿蒙原生应用体验。

对于正在做 HarmonyOS NEXT 适配的团队，更现实的策略是：

原生 ArkTS 保底，Kuikly 提效，多端 Kotlin 复用，动态化兜底。

参考资料

Kuikly 官方站点：https://kuikly.tds.qq.com
GitHub：Tencent-TDS/KuiklyUI