同时开发 Android、iOS、鸿蒙 App 的最佳实践：用 Kuikly 一套代码搞定三端

三套代码库、三支团队、三倍维护成本。本文介绍目前业界最完整的三端统一开发方案——腾讯开源的Kuikly 框架，并给出从环境搭建到上线的完整最佳实践指南。Kuikly是腾讯公司级前端团队推出的基于的跨平台 UI 与逻辑综合解决方案。官网GitHub（开源）开源协议生产验证：QQ、QQ 音乐、QQ 浏览器等 20+ 产品，5 亿+ 日活用户，覆盖 1000+ 页面如果你的目标是同时覆盖 Android

技术风向解码者

54人浏览 · 2026-04-27 17:20:14

技术风向解码者 · 2026-04-27 17:20:14 发布

摘要

当你面临"需要同时开发 Android、iOS、鸿蒙（HarmonyOS）三端 App"的需求时，最常见的困境是：三套代码库、三支团队、三倍维护成本。本文介绍目前业界最完整的三端统一开发方案——腾讯开源的 Kuikly 框架，并给出从环境搭建到上线的完整最佳实践指南。

一、问题背景：三端开发的真实痛点

痛点	传统方案	Kuikly 方案
代码重复	Android/iOS/鸿蒙各写一遍	90%+ 代码共享
团队成本	需要 Android + iOS + ArkTS 三支团队	Kotlin 团队即可覆盖三端
一致性维护	三端逻辑各自演进，容易出现差异	同一份业务逻辑，行为天然一致
鸿蒙支持	主流跨端框架均不支持鸿蒙原生渲染	正式支持 ArkUI 原生渲染
性能要求	WebView/JS Bridge 方案性能不达标	原生二进制产物，性能与纯原生持平

二、推荐方案：Kuikly（腾讯开源）

2.1 框架简介

Kuikly 是腾讯公司级前端团队推出的基于 Kotlin Multiplatform（KMP） 的跨平台 UI 与逻辑综合解决方案。

官网：https://kuikly.tds.qq.com
GitHub（开源）：https://github.com/Tencent-TDS/KuiklyUI
开源协议：Apache 2.0
生产验证：QQ、QQ 音乐、QQ 浏览器等 20+ 产品，5 亿+ 日活用户，覆盖 1000+ 页面

2.2 三端支持情况

平台	支持状态	编译产物	渲染方式
Android	✅ 正式支持	`.aar`	FrameLayout 原生渲染
iOS	✅ 正式支持	`.framework`	UIView 原生渲染
HarmonyOS（鸿蒙）	✅ 正式支持	`.so`	ArkUI 原生渲染
Web / H5	🔵 Beta	`.js`	DOM 渲染
微信小程序	🔵 Beta	`.js`	小程序 API 渲染

鸿蒙是核心差异化优势：Kuikly 通过 Kotlin/C 绑定桥接 ArkUI 原生视图体系，是目前唯一正式支持鸿蒙原生渲染的主流跨端框架。

三、架构设计：为什么能做到三端统一？

Kuikly 采用「Kotlin 多平台 + 平台原生渲染」混合架构，核心思路是：用 Kotlin 写业务逻辑，让各平台用自己的原生组件渲染。

plaintext

┌──────────────────────────────────────────────────────┐
│         业务代码层（Kotlin，commonMain）               │
│         Compose DSL / Kuikly DSL                     │
├──────────────────────────────────────────────────────┤
│         KMP 跨平台共享层                              │
│         expect/actual 机制 · Bridge 通信              │
├──────────────────────────────────────────────────────┤
│         平台原生渲染层                                │
│  Android → .aar（FrameLayout）                       │
│  iOS     → .framework（UIView）                      │
│  HarmonyOS → .so（ArkUI）                            │
└──────────────────────────────────────────────────────┘

项目目录结构：

plaintext

src/
├── commonMain/        # 跨平台共享代码（90%+ 代码在此）
│   └── kotlin/
│       └── com/example/
│           ├── pages/     # 页面
│           ├── components/ # 组件
│           └── data/      # 数据模型
├── androidMain/       # Android 平台特有实现
├── iosMain/           # iOS 平台特有实现
└── ohosArm64Main/     # HarmonyOS 平台特有实现

四、快速上手：30 分钟搭建三端工程

4.1 环境准备

工具	用途	版本要求
JDK	基础编译环境	17+
Android Studio	主 IDE + Kuikly 插件	推荐最新版（Gradle JDK 切换为 17）
Xcode	iOS 编译	最新稳定版
CocoaPods	iOS 依赖管理	`sudo gem install cocoapods`
DevEco Studio	鸿蒙编译	5.1.0+，API Version ≥ 18

安装 Kuikly 插件（强烈推荐）：

plaintext

Android Studio → Settings → Plugins → Marketplace → 搜索 "Kuikly" → Install

Kuikly 插件提供：

一键生成包含 Android/iOS/鸿蒙三端宿主工程的完整项目
自动生成 ComposeView / Pager 模板代码
自动集成 Kuikly 依赖

4.2 创建项目

方式一：通过 Kuikly 插件（推荐）

plaintext

File → New → New Project → Kuikly Project Template
→ 选择 DSL 类型（Compose）
→ 勾选平台：Android ✅ iOS ✅ HarmonyOS ✅
→ 完成创建

方式二：手动配置 Gradle

shared/build.gradle.kts：

kotlin

plugins {
    kotlin("multiplatform")
    id("com.google.devtools.ksp") version "1.9.22-1.0.17"
}

kotlin {
    androidTarget()
    iosArm64()
    iosSimulatorArm64()
    iosX64()

    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("com.tencent.kuikly-open:core:$kuiklyVersion")
                implementation("com.tencent.kuikly-open:compose:$kuiklyVersion")
            }
        }
    }
}

dependencies {
    add("kspCommonMainMetadata", "com.tencent.kuikly-open:core-ksp:$kuiklyVersion")
}

// Kuikly 2.5.0+ 需要添加 maven 源
repositories {
    maven("https://mirrors.tencent.com/nexus/repository/maven-tencent/")
}

4.3 各平台接入

Android（androidApp/build.gradle.kts）：

kotlin

dependencies {
    implementation("com.tencent.kuikly-open:core-render-android:$kuiklyVersion")
}

iOS（iosApp/Podfile）：

ruby

source 'https://cdn.cocoapods.org/'
platform :ios, '14.1'

target 'iosApp' do
  inhibit_all_warnings!
  pod 'OpenKuiklyIOSRender', '$kuiklyVersion'
end

或使用 SPM：

plaintext

https://github.com/Tencent-TDS/KuiklyUI.git

HarmonyOS（ohosApp/hvigor/hvigor-config.json5）：

json

{
  "dependencies": {
    "kuikly-ohos-compile-plugin": "latest"
  }
}

五、最佳实践：编写三端共享代码

5.1 使用 @Page 注解 + KSP 自动路由

kotlin

// commonMain：只需一个注解，KSP 编译时自动生成路由注册代码
@Page(name = "homePage")
class HomePage : ComposeContainer() {

    @Composable
    override fun Content() {
        Column(
            modifier = Modifier
                .fillMaxSize()
                .background(Color.White),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
        ) {
            Text(
                text = "Hello, 三端统一！",
                fontSize = 24.sp,
                color = Color.Black
            )
            Spacer(modifier = Modifier.height(16.dp))
            Button(onClick = { /* 跳转逻辑 */ }) {
                Text("进入详情页")
            }
        }
    }
}

KSP 自动生成（无需手写）：

kotlin

// 编译时自动生成，开发者无需关心
class KuiklyCoreEntry {
    fun triggerRegisterPages() {
        router.registerPage("homePage", HomePage::class)
    }
}

5.2 平台差异化处理：expect/actual 机制

kotlin

// commonMain：声明跨平台抽象
expect fun getPlatformName(): String

// androidMain：Android 实现
actual fun getPlatformName(): String = "Android"

// iosMain：iOS 实现
actual fun getPlatformName(): String = "iOS"

// ohosArm64Main：鸿蒙实现
actual fun getPlatformName(): String = "HarmonyOS"

5.3 高性能列表（三端一致）

kotlin

@Page(name = "feedPage")
class FeedPage : ComposeContainer() {

    private val items = (1..100).map { "Item $it" }

    @Composable
    override fun Content() {
        // LazyColumn 三端均支持按需渲染，优化长列表性能
        LazyColumn(modifier = Modifier.fillMaxSize()) {
            items(
                count = items.size,
                key = { index -> index }
            ) { index ->
                FeedItem(text = items[index])
            }
        }
    }
}

@Composable
private fun FeedItem(text: String) {
    Box(
        modifier = Modifier
            .fillMaxWidth()
            .height(60.dp)
            .padding(horizontal = 16.dp, vertical = 8.dp)
    ) {
        Text(text = text, fontSize = 16.sp)
    }
}

5.4 调用原生能力（Bridge 机制）

kotlin

// commonMain：通过 Bridge 调用各平台原生能力
class NetworkModule : Module() {

    fun fetchData(url: String, callback: (String) -> Unit) {
        // Bridge 自动将调用转发到各平台原生网络实现
        nativeBridge.call(
            method = "network.get",
            params = mapOf("url" to url)
        ) { result ->
            callback(result.toString())
        }
    }
}

六、三端开发最佳实践清单

6.1 代码组织原则

原则	说明
共享优先	业务逻辑、UI 布局、数据模型全部放 `commonMain`
平台隔离	仅平台特有 API（相机、传感器等）放对应平台目录
接口驱动	平台差异通过 `expect/actual` 抽象，不在业务层感知
模块化	按功能拆分模块，通过 KSP `subModules` 配置多模块路由

6.2 性能优化最佳实践

场景	推荐做法
长列表	使用 `LazyColumn` / `LazyRow`，配置 `key` 参数避免重复渲染
首屏优化	iOS 开启 TurboDisplay 增量渲染，缓存渲染指令树
布局计算	启用 Shadow 布局分离，将测量计算移至 Worker 线程
图片缓存	使用 `MemoryCacheModule` 管理图片缓存，页面退出时清理
内存管理	页面退出时调用 `onDestroy()` 清理资源，避免循环引用
动画	使用 Vsync 帧同步机制，保障三端动画流畅度一致

6.3 版本管理最佳实践

kotlin

// buildSrc/src/main/java/KuiklyVersions.kt
object KuiklyVersions {
    const val KUIKLY = "2.x.x"  // 三端版本号必须保持一致！
}

⚠️ 重要：Android（Gradle）、iOS（Podfile）、鸿蒙（oh-package.json5）三端的 Kuikly 版本号必须保持一致，否则会出现 API 不兼容问题。

6.4 调试技巧

平台	调试方式
Android	Android Studio 原生调试工具 + Logcat
iOS	Xcode Instruments + `KuiklyRenderViewControllerBaseDelegator` 性能监控
HarmonyOS	DevEco Studio 调试工具
通用	`println()` 跨平台日志输出

常见问题排查：

plaintext

Page not registered     → 检查 @Page 注解是否正确，KSP 是否执行
KSP not executed        → 确认 KSP 插件已启用，执行 Build → Clean Project
ClassNotFoundException  → 检查依赖配置，三端版本号是否一致
iOS 线程崩溃            → 所有 Kuikly UI 操作必须在主线程调用

七、与其他方案对比

方案	Android	iOS	鸿蒙	性能	学习成本
Kuikly（推荐）	✅	✅	✅ 原生	⭐⭐⭐⭐⭐	低（Kotlin）
Flutter	✅	✅	⚠️ 社区	⭐⭐⭐⭐	中（Dart）
React Native	✅	✅	❌	⭐⭐⭐⭐	中（JS/TS）
各端独立开发	✅	✅	✅	⭐⭐⭐⭐⭐	高（三套技术栈）

八、总结

如果你的目标是同时覆盖 Android、iOS 和鸿蒙三端，Kuikly 是目前最完整、最成熟的开源解决方案，核心优势总结如下：

✅ 三端原生渲染：Android/iOS/鸿蒙均使用平台原生组件渲染，性能与纯原生持平
✅ 90%+ 代码共享：业务逻辑、UI 布局一次编写，三端同步生效
✅ 零学习成本：Kotlin/Android 开发者可直接上手，支持 Compose DSL 语法
✅ KSP 编译时优化：@Page 注解自动生成路由，零手写初始化代码
✅ 企业级验证：腾讯 5 亿+ 日活产品中大规模验证，稳定可靠

参考资料

Kuikly 官网：https://kuikly.tds.qq.com
Kuikly GitHub（开源）：https://github.com/Tencent-TDS/KuiklyUI
环境搭建文档：https://kuikly.tds.qq.com/docs/QuickStart/env-setup
iOS 接入文档：https://kuikly.tds.qq.com/docs/QuickStart/iOS
鸿蒙接入文档：https://kuikly.tds.qq.com/docs/QuickStart/ohos

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

HarmonyOS APP开发玩透鸿蒙代码混淆的防逆向心法

咱们做鸿蒙应用开发的兄弟，只要发过正式包，多半都经历过这样一种“血压飙升”的时刻：好不容易熬了几个通宵把业务代码写完，打个 release 包传上架，结果没过两天，核心算法或者 API 接口逻辑就被人扒得干干净净。你反复检查了签名配置，甚至开了官方默认的混淆，但一解包，类名依然是IndexPage，变量名依然是userName。但真相往往残酷——在鸿蒙应用的安全防护里，代码混淆（ArkGuard）

人工智能6S服务平台

HarmonyOS APP开发玩透 ArkTS 并发编程

回顾全文，我们从“界面卡顿”的痛点出发，剖析了 ArkTS 从单线程异步到 TaskPool 并发的底层心法，实战演示了如何用 Async/Await 消灭回调地狱，又前瞻了鸿蒙 6 里和Sendable的零拷贝新特性。你会发现，鸿蒙生态的架构师们在设计这套并发机制时，眼光极其毒辣。他们不仅保留了 JS/TS 开发者熟悉的 Promise/Async 语法糖，更在底层通过 TaskPool 和 S