【2026 最新】Kuikly 编译开发 OpenHarmony 项目逐步详细教程带图操作Android Studio编译（Windows）

引言

随着开源鸿蒙（OpenHarmony）生态的快速成熟与广泛应用，越来越多的开发者希望借助高效、跨平台的 UI 框架加速应用开发。KuiklyUI 作为专为 OpenHarmony 打造的现代化轻量级 UI 库，凭借其简洁的语法、良好的组件封装能力以及"一次开发、多端部署"的天然优势，正成为社区中备受关注的开发选择。

截至 2026 年初，OpenHarmony 已发布至 6.0 Release 版本，API 能力持续演进，配套工具链也日趋完善。与此同时，KuiklyUI 社区生态不断壮大，提供了丰富的示例工程与文档支持，极大降低了入门门槛。然而，对于 Windows 平台的开发者而言，从零搭建 Kuikly + OpenHarmony 的开发环境仍存在一定的配置复杂度------包括 DevEco Studio 的正确安装、Node.js 与 OHPM 依赖管理、项目模板拉取、以及最终的编译运行等环节，稍有不慎便可能导致构建失败。

本文旨在为 Windows 用户提供一份最新、完整、图文并茂的 Kuikly 开发 OpenHarmony 项目的实操指南。我们将从环境准备开始，逐步引导您完成 Kuikly 项目创建、代码结构解析、本地调试及真机/模拟器运行全过程，助您快速迈入开源鸿蒙应用开发的大门。

一、基础环境准备

1.1 创建必要文件夹

首先在除C盘以外的盘建立文件夹，分别保存软件位置，JDK位置与SDK位置

特别注意：所有文件名中不要出现空格且中文，而且每个文件夹都是为空的状态！

特别注意：所有文件名中不要出现空格且中文，而且每个文件夹都是为空的状态！

特别注意：所有文件名中不要出现空格且中文，而且每个文件夹都是为空的状态！

重要的的事情说三边！

这里我是在F盘中操作，大家可以直接按照我的文件夹名称创建。

下述的Jdk 17文件夹可以先不创建，如果在安装 Android Studio 2023.3.1 JDK下载有问题时再创建。

1.2 安装JDK 17环境

对于 二、安装 Android Studio 2023.3.1 版本安装时内置了JDK17版本；

所以这里仅供在安装Android Studio 2023.3.1时出现问题没有 JDK 17的人使用；

刚开始这一步可以先跳过，直接开始二、安装 Android Studio 2023.3.1；

安装配置JDK教程，这里安装的是JDK17的版本，如果以前安装过，此步可以跳过：

1.2.1 下载JDK

地址：

https://www.oracle.com/https://www.oracle.com/

1.2.2 配置JDK

解压jdk，找到jdk目录

复制地址路径

点开高级系统设置

点击新建：

输入以下配置

JAVA_HOME

这是你安装jdk的位置

F:\Chengxusheji\Android\jdk-17.0.13

找到path双击打开

新建

%JAVA_HOME%\bin

一路点确定即可

1.2.3 验证是否配置成功

用组合键win+R，打开运行，在编辑框内输入"cmd"打开命令提示符，输入java -version然后回车运行，出现下图，说明已经配置成功，否则则需要配置JDK。

二、安装Android Studio

2.1 下载地址

官网：

Android Studio download archives | Android Developers

往下翻下载稳定版本 Android Studio Jellyfish | 2023.3.1 April 30, 2024

2.2 下载完成后，解压到studio目录中

打开studio，再点android-studio，找到bin中studio64.exe文件

2.3 右键显示更多选项，发送到桌面快捷方式

2.4 然后双击打开

2.5 选择自定义安装

修改成你自己的下载路径：

对应你新增的sdk文件夹

2.6 等待安装

这里安装建议不要用校园网，建议用热点（如果有大学生安装，请参考），如果校园网非常快的话，也可以用校园网。

2.7 点击完成

如果有弹出以下点击红圈里：

选择你刚才安装sdk的位置

三、安装必要的插件

3.1 安装Kotlin和Kotlin MultiPlatform插件

在Android Studio中安装必要的Kotlin插件：

1. Plugins → Marketplace
2. 在搜索框中输入"Kotlin"
3. 安装以下插件：
4. Kotlin （新版Android Studio内置）
5. Kotlin MultiPlatform Mobile

下载好后，已下载里面会显示

3.2 安装Kuikly插件

下载好后重新打开Android Studio

3.3 开始新建项目

等待下载

稍后Gradle会自动下载依赖

嫌速度下载慢的，加快Gradle下载速度配置，换成腾讯镜像源

distributionUrl=https://mirrors.cloud.tencent.com/gradle/gradle-8.6-bin.zip

配置好依赖后，点击Try Again重新下载；如果没有显示Try Again就关闭项目重新打开

上方出现运行按钮说明依赖下载成功：

3.4 在Android中运行项目

点击绿色运行按钮进行运行，前提你有一个安卓虚拟机

3.4.1 没有安卓虚拟机的点击

3.4.2 大家可以根据自己的需求进行选择

例如我这里选择的是Small Phone

3、这里是需要下载所需虚拟手机镜像

4、等待安装

3.5 切换Gradle版本（版本不匹配时再切换）

Kuikly项目对Gradle版本有特定要求，需要进行正确配置：

重要：如果遇到Gradle版本不匹配情况，请将Gradle版本切换成7.x (推荐7.5.1)。

切换方式：

• File → Project Structure → Project → Gradle Version
• 选择7.5.1版本

加快Gradle下载速度配置，换成腾讯镜像源

distributionUrl=https://mirrors.cloud.tencent.com/gradle/gradle-7.5.1-bin.zip

配置好依赖后，点击Try Again重新下载；如果没有显示Try Again就关闭项目重新打开

3.6 忽略iOS编译配置（不是必需步骤，暂时没遇到问题）

由于Windows平台无法运行iOS开发环境，必须修改项目配置以忽略iOS相关编译：

1. 在Android Studio中，切换到Project视图
2. 找到并打开shared/build.gradle.kts文件
3. 注释掉所有iOS相关配置，具体需要注释的内容如下：

// 注释以下插件
// plugins {
//    kotlin("native.cocoapods")
// }

kotlin { 
   // ... 其他配置保持不变
   
   // 注释以下iOS目标平台
   // iosX64()
   // iosArm64()
   // iosSimulatorArm64()
   
   // 注释cocoapods配置
   // cocoapods {
   //    summary = "Some description for the Shared Module"
   //    homepage = "Link to the Shared Module homepage"
   //    version = "1.0"
   //    ios.deploymentTarget = "14.1"
   //    podfile = project.file("../iosApp/Podfile")
   //    framework {
   //        baseName = "shared"
   //        isStatic = true
   //        license = "MIT"
   //    }
   // }
   
   // ... 其他配置保持不变
   
   // 注释iOS源集配置
   // val iosX64Main by getting
   // val iosArm64Main by getting
   // val iosSimulatorArm64Main by getting
   // val iosMain by creating {
   //    dependsOn(commonMain)
   //    iosX64Main.dependsOn(this)
   //    iosArm64Main.dependsOn(this)
   //    iosSimulatorArm64Main.dependsOn(this)
   // }
   // val iosX64Test by getting
   // val iosArm64Test by getting
   // val iosSimulatorArm64Test by getting
   // val iosTest by creating {
   //    dependsOn(commonTest)
   //    iosX64Test.dependsOn(this)
   //    iosArm64Test.dependsOn(this)
   //    iosSimulatorArm64Test.dependsOn(this)
   // }
}

dependencies {
   // ... 其他依赖保持不变
   
   // 注释iOS ksp依赖
   // add("kspIosArm64", this)
   // add("kspIosX64", this)
   // add("kspIosSimulatorArm64", this)
}

3.7 常见报错

Your build is currently configured to use incompatible Java 21.0.8 and Gradle 7.5.1. Cannot sync the project.

We recommend upgrading to Gradle version 9.0-milestone-1.

The minimum compatible Gradle version is 8.5.

The maximum compatible Gradle JVM version is 18.

Possible solutions:

• Upgrade to Gradle 9.0-milestone-1 and re-sync

• Upgrade to Gradle 8.5 and re-sync

这个错误是因为 Java 版本与 Gradle 版本不兼容。

• 你当前使用的是 Java 21.0.8（即 JDK 21）。
• 但你的项目配置的是 Gradle 7.5.1。
• Gradle 7.5.1 不支持 JDK 21！只支持 JDK 17

如果你的Android Studio版本大于等于2024.2.1，请将Gradle JDK版本切换为JDK17。

如果没有JDK 17借鉴步骤1.2 安装JDK 17环境进行安装配置

这是因为该版本默认Gradle JDK为21，与Kuikly项目使用的配置不兼容。

切换方式：

• Android Studio → Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JDK
• 选择JDK 17版本

三、安装OpenHarmony开发环境

3.1 安装DevEco Studio

由于需要开发OpenHarmony应用，必须安装DevEco Studio：

见文章：【2025 最新】最新HarmonyOS 6 DevEco Studio下载安装 详细步骤（带图展示）_harmonyos模拟器下载-CSDN博客

3.2 记下OpenHarmony SDK位置

记下SDK安装路径，后续Kuikly项目配置需要

F:\Chengxusheji\HarmonyOS\DevEco Studio\sdk\default\openharmony

四、Windows平台OpenHarmony编译配置

Windows平台上编译OpenHarmony应用需要特殊配置，因为鸿蒙平台跨端产物需要使用鸿蒙SDK的LLVM工具编译生成，官方版的Kotlin工具链并不支持鸿蒙平台。Kuikly使用定制版的Kotlin工具链来支持Windows平台编译。

4.1 环境配置

在Windows平台配置，需指定OHOS SDK位置，配置环境变量：

右键点击此电脑，点击属性 → 高级系统设置 → 环境变量

新建系统变量：

• 变量名：

OHOS_SDK_HOME

• 变量值：

F:\Chengxusheji\HarmonyOS\DevEco Studio\sdk\default\openharmony（请替换为你的实际安装路径）

确保该路径下包含OpenHarmony Sdk

重要：这里需要重启电脑才能生效！

重要：这里需要重启电脑才能生效！

重要：这里需要重启电脑才能生效！不然后面编译时会报错

4.2 配置Kuikly OpenHarmony编译环境

方式1：OpenHarmony单独配置编译链（推荐）

给OpenHarmony单独配置Gradle配置项，使用此配置项编译鸿蒙产物：

• 在项目根目录下创建或修改settings.ohos.gradle.kts文件
• 配置定制版Kotlin工具链，示例配置如下：

pluginManagement {
    repositories {
        google()
        gradlePluginPortal()
        mavenCentral()
        mavenLocal()
        maven {
            url = uri("https://mirrors.tencent.com/nexus/repository/maven-tencent/")
        }
    }

    plugins {
        kotlin("android").version("2.0.21-KBA-010").apply(false)
        kotlin("multiplatform").version("2.0.21-KBA-010").apply(false)
        // 其他插件配置
    }
}

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        mavenLocal()
        maven {
            url = uri("https://mirrors.tencent.com/nexus/repository/maven-tencent/")
        }
    }
}

rootProject.name = "MyApplication"

val buildFileName = "build.ohos.gradle.kts"
rootProject.buildFileName = buildFileName

include(":androidApp")
include(":shared")
project(":shared").buildFileName = buildFileName

命令介绍（可以跳转到步骤 4.3 Windows平台编译步骤 开始编译）

• 编译命令：

./gradlew -c settings.ohos.gradle.kts :shared:linkOhosArm64

仅编译Debug产物：

./gradlew -c settings.ohos.gradle.kts :shared:linkDebugSharedOhosArm64

仅编译Release产物：

./gradlew -c settings.ohos.gradle.kts :shared:linkReleaseSharedOhosArm64

方式2：统一编译链形式

如果希望在IDE中获得更好的代码提示，可以将OpenHarmony工具链作为默认设置：

• 在项目根目录的build.gradle.kts中添加Maven源：

repositories {
    // 定制版kotlin工具链
    maven {
        url = uri("https://mirrors.tencent.com/nexus/repository/maven-tencent/")
    }
}

• 修改Kotlin版本：

plugins {
    kotlin("android").version("2.0.21-KBA-010").apply(false)
    kotlin("multiplatform").version("2.0.21-KBA-010").apply(false)
    // 其他插件
}

• 在shared/build.gradle.kts中修改Kuikly依赖版本：

sourceSets {
    val commonMain by getting {
        dependencies {
            // KUIKLY_VERSION 用实际使用的Kuikly版本号替换
            implementation("com.tencent.kuikly-open:core:KUIKLY_VERSION-2.0.21-KBA-010")
            implementation("com.tencent.kuikly-open:core-annotations:KUIKLY_VERSION-2.0.21-KBA-010")
        }
    }
}

• 添加OpenHarmony构建目标：

kotlin {
    ohosArm64 {
        binaries {
            sharedLib()
        }
    }
}

dependencies {
    compileOnly("com.tencent.kuikly-open:core-ksp:KUIKLY_VERSION-2.0.21-KBA-010") {
        // 配置...
    }
    add("kspOhosArm64", this)
}

4.3 Windows平台编译步骤

由于Windows Android Studio上暂未适配sh脚本运行，不能直接通过runOhosApp.sh联动编译OpenHarmony APP。OpenHarmony APP编译需要分两步：

Step 1：编译OpenHarmony跨端产物

在Android Studio中，通过命令行编译OpenHarmony跨端产物，并将编译后的产物拷贝到OpenHarmony APP对应目录：

打开Android Studio的Terminal

执行编译命令：

./gradlew -c settings.ohos.gradle.kts :shared:linkOhosArm64

等待编译成功：

Step 2：移动到OpenHarmony项目中

将生成的so文件和头文件复制到OpenHarmony项目中：

• so文件位置：shared/build/bin/ohosArm64/releaseShared/libshared.so
• 头文件位置：shared/build/bin/ohosArm64/releaseShared/libshared_api.h
• 复制到OpenHarmony项目的entry/libs/arm64-v8a/和entry/src/main/cpp/目录
• 步骤如下：

• 复制到

• "libshared.h"文件：把该文件移植到鸿蒙的entry/src/main/cpp/目录中。
• "libshared.so"文件：我们一打开是没有lib文件夹的。我们需要在entry目录下新建libs文件夹，再在"libs"文件夹下新建"arm64-v8a"文件夹，最后在"arm64-v8a"文件夹下放置"libshared.so"文件。

4.4 运行到真机

注意：Windows平台无法使用模拟器运行！需要真机或者云真机

云真机申请链接：https://developer.huaweicloud.com/space/devportal/platform/cloudPhone

运行到真机效果如图所示：