Kuikly 是腾讯开源的 Kotlin Multiplatform 跨端框架。

它处理的不是单纯的业务逻辑复用，而是把 UI、布局、事件、Bridge 和部分业务逻辑都放到 KMP 工程里再分别编译到 Android、iOS、鸿蒙、Web、小程序和 macOS。

你可能遇到的痛点

• 代码只能在单一网站跑：传统 Android 项目想要快速 到 iOS 或 Web。往往需要重写 UI 层，维护成本高。
• 跨端 UI 一致性差：使用原生控件或各网站独立实现时页面细节经常出现不统一。
• 业务代码与 UI 代码耦合：业务逻辑散落在多个模块，改动时容易遗漏或产生冲突。
• 引入第三方跨网站框架成本大：Dart或 JS需要全新技术栈，对已有 Kotlin/Android 团队学习成本高。
• 动态化发布困难：大体量 App 需要灰度发布、热更新，但传统原生方案缺少统一的页面产物管理。

它解决什么问题

Android 开发看跨网站框架时通常会先问两个问题：一份代码能不能跑到多个网站，跑起来以后是不是还能保留接近原生的体验。Kuikly 的设计比较明确，它用 Kotlin Multiplatform 写跨端业务。再用各个网站自己的 Render 层做真正的 UI 渲染。

它的工程里有两个主要概念：KuiklyCore 和 KuiklyRender。KuiklyCore 负责跨网站的声明式 UI、响应式更新、布局算法和 Bridge 通信；KuiklyRender 负责把 Core 声明出来的控件渲染到具体网站上。Android 上是比如 Android 渲染器。iOS 上是 iOS 渲染器，鸿蒙，还有Web，再有小程序也都有对应实现。

这和很多“写一套 UI，接下来用统一引擎画出来”的方案不太一样。Kuikly 更接近一套跨端 UI 协议：业务代码在 KMP 侧声明页面结构和状态变化，网站侧提供承载容器、生命周期、图片、日志、路由、线程等适配能力。怎么说呢，

从开源仓库看。Kuikly 目前支持 Android、iOS、HarmonyOS、Web、小程序和 macOS。其中 Web、小程序还标注为 娱乐a，macOS 是 Alpha。程序要求里 Android 是 +，iOS 是 +。HarmonyOS Next 是 .+。这些版本信息决定了它不是只面向新项目，老 Android 设备也在覆盖范围里。不过，

README 里还有一个信息比较具体：AOT 模式下 Android SDK 增量大约 K​BiOS 大约 M​B。这个数字不能直接等同于业务最终包体积，因为还要看具体页面、资源、依赖和网站接入方式。但至少说明它没有把一个很重的通用渲染引擎塞进宿主。老实说，

工程结构

Kuikly 的源码结构能看出它的分层：

• core: 跨网站模块，包含 commonMain,androidMain,jvmMain,appleMain,ohosArm64Main。jsMain
• *-render-android / ios / ohos / web: 各网站渲染实现
• core-annotations: @Page 注解定义
• core-ksp: 注解处理器，实现页面注册与生成代码

AAR、framework、SO还有 JS 包分别对应不同 target 的产物。

Kotlin 示例页面

@Page
internal class HelloWorldPage : Pager {
override fun body: ViewBuilder {
return {
attr { allCenter }
Text {
attr {
text
fontSize
}
}
}
}
}

This code highlights three key points:

• Pager: Kuikly 页面基类；老实说，
• @Page: 注册运行时可打开的页面名； 老实说，
• endbody: 返回声明式 UI 内容。

The syntax resembles Jetpack Compose,but Kuikly uses its own DSL. The repository also ships a /compose module that adapts Jetpack Compose APIs under package com.tencent.kuikly.compose。avoiding a direct copy‑paste of official Compose Multiplatform library.

创建项目 & 快速上手教程

Pain point: 很多团队不知道从哪里开始，也不清楚多端工程到底要准备哪些文件。

1. Create project via Android Studio plugin:

File → New → New Project → Kuikly Project Template

2. Main generated modules:
• /shared/…​/src/commonMain/kotlin/…说起来，​ : 编写跨端页面与业务逻辑
• /androidApp/ …其实，​ : Android 壳工程
• /iosApp/ …​ : iOS 壳工程
• /ohosApp/。/h5App/,/miniApp/…​ : 鸿蒙 / Web / 小程序壳
3. Troubleshooting tip: 如果 Gradle sync 卡住请确认已添加腾讯 Maven 源：

   repositories {
   maven
   }
   

4. Select a platform to run:
• A ndroid: 直接运行 /androidApp/src/main/java/.../MainActivity.kt
• I O S: 进入 /iosApp/ 并执行

  pod install --repo-update
  xcrun simctl boot "iPhone 14"
  ./gradlew iosApp:assembleDebug
  open iosApp.xcworkspace
  

• H5 :启动 dev server 并建立 JS Bundle： bash npm run serve ./gradlew :shared:packLocalJsBundleDebug ./gradlew :h5App:jsBrowserRun -t
• Mini‑app :编译为 JS 并打开微信开发者工具： bash ./gradlew :shared:packLocalJsBundleDebug ./gradlew :miniApp:jsMiniAppDevelopmentWebpack

常见坑 & 对策

• 版本不一致core 与 core‑render 必须使用相同版本号，否则会出现运行时 Bridge 调用失效。检查 build.gradle.kts 中 KUIKLY_CORE_VERSION 与 KUIKLY_RENDER_VERSION 是否同步。
• Maven 源未配置未添加腾讯镜像会导致依赖下载失败。务必在根项目 repositories 中加入上述地址。
• 渲染容器缺失宿主必须提供 KuiklyRenderViewBaseDelegator 并转发生命周期，否则页面不会显示或会泄漏资源。不过，
• 适配器未实现图片加载、日志上报等适配器如果返回空实现。会导致 Crash 或埋点缺失。建议先复用宿主已有实现再逐步替换。

If you want to integrate Kuikly into an existing Android app,split work into two parts: adding KMP core and wiring up render layer.

Add dependencies

repositories {
maven
}
dependencies {
implementation
implementation
// 你的常规依赖…话说回来，}

Create a host activity 

class KuiklyHostActivity : AppCompatActivity {
private lateinit var delegator: KuiklyRenderViewBaseDelegator
private lateinit var contextHandler: ContextCodeHandler
private lateinit var container: ViewGroup
override fun onCreate {
super.onCreate
setContentView // 包含 id=hr_container 的 FrameLayout
container = findViewById
// pageName 可以通过 Intent 参数传递。也可以写死用于演示
val pageName = intent.getStringExtra?: "HelloWorld"
contextHandler = ContextCodeHandler
delegator = contextHandler.initContextHandler
contextHandler.openPage(
this,container,pageName。createPageData // 可选：向页面传递初始化参数
)
}
override fun onResume {
super.onResume
delegator.onResume
}
override fun onPause {
super.onPause
delegator.onPause
}
override fun onDestroy {
super.onDestroy
delegator.onDetach
}


}





ImageAdapter – 使用 Glide / Picasso 等宿主库包装成 ImageAdapter 接口；* LogAdapter – 将日志转发至现有埋点程序；* ExceptionAdapter – 捕获并上报异常；* RouterAdapter – 把 Kuikly 的路由请求映射为宿主 Activity/Fragment 跳转；* ThreadAdapter – 把 runOnUiThread 与后台线程调度交给宿主线程池。





Kotlin Multiplatform + Kuikly
PFlutter
BReact Native
ECompose Multiplatform




Coding language Kotlin
无额外语言学习成本
Dart
Scripting
Kotlin + Compose DSL 

UI Rendering 
Platform‑native renderer + shared DSL  
Skia engine  
Bridge + native view hierarchy  
Compose runtime directly on each platform  

Business logic reuse 
Full KMP share  
Logic一般放在 Dart side。需要桥接  
Logic 在 JS side，一样需要桥接 
仅共享逻辑，不含 UI 渲染 

Platform coverage aarch64‑Android,iOS‑arm64,HarmonyOS‑arm64,Web‑JS,Mini‑programs,macOS  Dart VM + native engine → Android/iOS/Web/Desktop  Scripting → Android/iOS/Web  KMP+Compose → Android/JVM/Desktop/iOS  

Dynamic module delivery AOT + incremental bundle → 可按需下发页面包 No built‑in dynamic delivery   No built‑in dynamic delivery  No built‑in dynamic delivery  

Learning curve for an existing Kotlin team 低——只需掌握 DSL 与 Render 接口  高——全新语言+IDE 配置  & t d style =" color:#8B0000;">高——JS 桥接模型与原生插件程序 & n bsp;其实，t d style =" color:#006400;">中——已熟悉 Compose,学习成本相对平缓 & n bsp;t d>