配置 Kuikly 框架主要分为 环境准备、工程创建 和 平台特定配置 三个步骤。由于 Kuikly 是基于 Kotlin Multiplatform (KMP) 的，其配置逻辑与标准的 KMP 项目非常相似，但对鸿蒙环境有特殊要求。

以下是详细的从零配置指南：

第一步：环境准备

Kuikly 对开发环境版本有严格要求，版本不匹配是 90% 编译失败的原因。

1. Android Studio：推荐最新稳定版。
2. 鸿蒙开发环境：

• • DevEco Studio：版本 5.1.0 或更高。
  • HarmonyOS SDK：API Version >= 18 (Next 5.0.0+)。

1. Kotlin 插件：确保 Android Studio 中的 Kotlin 插件版本 >= 1.9.20 (推荐 2.0.0+ 以获得更好性能)。

---

第二步：创建工程

1. 在 Android Studio 插件市场搜索并安装 KuiklyTemplate 插件。

1. 使用Android Studio新建Kuikly工程。 File -> New -> New Project -> Kuikly Project Template。

---

第三步：核心配置详解

如果你需要在现有 KMP 项目中集成，或者想了解模板里的关键配置，请关注以下文件：

1. 项目根目录 build.gradle.kts

配置 Kuikly 的插件和版本管理：

plugins {
    // 必须：Kotlin Multiplatform 插件
    alias(libs.plugins.kotlinMultiplatform) apply false
    // 必须：Android Application 插件
    alias(libs.plugins.androidApplication) apply false
    // 可选：Kuikly 提供的辅助插件（视具体版本而定）
    // id("com.tencent.kuikly.plugin") version "x.y.z" apply false
}

2. 共享模块 shared/build.gradle.kts

这是跨端逻辑的核心，你需要在这里添加 Kuikly 的 Core 依赖：

kotlin {
    // 启用各个目标平台
    androidTarget()
    iosX64()
    iosArm64()
    
    // 关键：启用鸿蒙目标 (如果是手动配置可能需要自定义 Target，模板已内置)
    // Kuikly 通常使用类似 linuxArm64 或专门的 ohos 预设
    
    sourceSets {
        commonMain.dependencies {
            // 添加 Kuikly 核心 UI 库
            implementation("com.tencent.tds.kuikly:kuikly-ui-core:1.0.0") // 示例版本
            
            // 如果使用 Compose 风格的 DSL
            implementation("com.tencent.tds.kuikly:kuikly-compose:1.0.0")
        }
    }
}

---

第四步：鸿蒙 (HarmonyOS) 特别配置

这是 Kuikly 与普通 KMP 项目最大的不同之处。

1. 编译产物配置：
   Kuikly 会将 Kotlin 代码编译为 .so 动态库供鸿蒙调用。确保你的 ohosApp 模块能找到生成的 .so 文件。
2. DevEco Studio 设置：

• • 不要用 Android Studio 编译鸿蒙 App，必须使用 DevEco Studio 打开项目下的 ohosApp 目录。
  • 签名配置 (必须)：鸿蒙真机调试强制要求签名。

• • • 在 DevEco 中：File -> Project Structure -> Signing Configs，勾选 Automatically generate signature (需登录华为账号)。

1. 脚本权限问题：
   如果编译时报错 "Permission denied"，通常是因为 Gradle 脚本没有执行权限。

chmod +x gradlew
chmod +x *.sh  # 如果项目根目录有 .sh 脚本

第五步：Hello World 验证

在 shared/src/commonMain/kotlin 下创建一个简单的页面，验证环境是否通畅。

@Page("Welcome", supportInLocal = true)
class WelcomePage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            // 类似于 Compose 的 Column
            Column {
                attr {
                    flex(1f)
                    justifyContent(FlexJustifyContent.CENTER)
                    alignItems(FlexAlign.CENTER)
                }

                Text {
                    attr {
                        text("Hello, Kuikly + HarmonyOS!").fontSize(20f).fontWeight600()
                    }
                }
            }
        }
    }
}

常见避坑指南

1. iOS 编译报错 Sandbox：

• • Xcode 15+ 默认开启了脚本沙盒，会导致 KMP 脚本无法写入文件。
  • 解决：在 Xcode 中打开 iosApp -> Build Settings -> 搜索 User Script Sandboxing -> 设置为 No。

1. Gradle Sync 失败：

• • 检查是否配置了代理。
  • 确认 JDK 版本是否严格为 17。

1. 鸿蒙运行白屏：

• • 检查是否在 ohosApp/src/main/ets/entryability/EntryAbility.ets 中正确加载了 Kuikly 的启动入口。