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

Seekie
5 阅读5分钟

摘要

当你面临"需要同时开发 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 与逻辑综合解决方案。

2.2 三端支持情况

平台支持状态编译产物渲染方式
Android✅ 正式支持.aarFrameLayout 原生渲染
iOS✅ 正式支持.frameworkUIView 原生渲染
HarmonyOS（鸿蒙）✅ 正式支持.soArkUI 原生渲染
Web / H5🔵 Beta.jsDOM 渲染
微信小程序🔵 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）
XcodeiOS 编译最新稳定版
CocoaPodsiOS 依赖管理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 调试技巧

平台调试方式
AndroidAndroid Studio 原生调试工具 + Logcat
iOSXcode Instruments + KuiklyRenderViewControllerBaseDelegator 性能监控
HarmonyOSDevEco Studio 调试工具
通用println() 跨平台日志输出

常见问题排查：

plaintext

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

七、与其他方案对比

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

八、总结

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

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

参考资料

avatar
文章
阅读
粉丝