【开源鸿蒙跨平台开发--KuiklyUI】Windows平台Kuikly OpenHarmony开发环境搭建指南

Windows平台Kuikly OpenHarmony开发环境搭建指南

引言

Kuikly是基于Kotlin MultiPlatform(KMP)实现的一套跨平台应用框架，它支持开发Android、iOS和OpenHarmony应用。对于Windows平台的开发者来说，搭建完整的Kuikly OpenHarmony开发环境有一些特殊的注意事项。本文将详细介绍在Windows系统上如何搭建Kuikly OpenHarmony的开发环境，帮助开发者快速开始跨平台应用开发。

1. 基础环境准备

1.1 安装Android Studio

首先需要下载并安装最新版本的Android Studio。访问Android Studio官网下载Windows版本的安装包，按照安装向导完成安装。

[Android Studio下载页面]

[我的Android Studio版本]

重要提示：如果你的Android Studio版本大于等于2024.2.1，请将Gradle JDK版本切换为JDK17。这是因为该版本默认Gradle JDK为21，与Kuikly项目使用的配置不兼容。

切换方式：

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

[Gradle JDK设置界面（全局设置）]

1.2 配置JDK 17环境

Kuikly项目需要JDK 17作为基础环境。如果尚未安装JDK 17，请按以下步骤操作：

1. 访问Oracle JDK下载页面或OpenJDK网站下载JDK 17
2. 安装JDK 17到本地目录，例如：C:\Program Files\Java\jdk-17
3. 配置环境变量：
   • 新建系统变量JAVA_HOME，值为JDK安装路径
   • 在Path变量中添加%JAVA_HOME%\bin
4. 验证安装：打开命令提示符，输入java -version，确认显示JDK 17版本信息

2. 安装必要的插件

2.1 安装Kotlin和Kotlin MultiPlatform插件

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

1. 打开Android Studio
2. 导航到：Settings → Preferences → Plugins → Marketplace
3. 在搜索框中输入"Kotlin"
4. 安装以下插件：
   • Kotlin （新版Android Studio内置）
   • Kotlin MultiPlatform Mobile

[Kotlin和KMP插件安装界面]

2.2 安装Kuikly插件

Kuikly插件提供了项目模板、代码生成等实用功能，特别是对于OpenHarmony开发非常有帮助：

1. 打开Android Studio
2. 导航到：Settings → Preferences → Plugins → Marketplace
3. 在搜索框中输入"Kuikly"
4. 点击Install按钮安装插件
5. 安装完成后，重启IDE

特别提示：若想通过插件生成OpenHarmony工程，请确保安装1.1.0版本以上的Kuikly插件。

[Kuikly插件安装界面]

3. 安装OpenHarmony开发环境

3.1 安装DevEco Studio

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

1. 访问OpenHarmony官网或DevEco Studio下载页面
2. 下载Windows版本的DevEco Studio
3. 按照安装向导完成安装
4. 配置DevEco Studio，包括SDK下载和环境设置

3.2 配置OpenHarmony SDK

安装完DevEco Studio后，需要配置OpenHarmony SDK：

1. 打开DevEco Studio
2. 在欢迎页面点击"Configure" → “SDK Manager”
3. 选择并下载所需版本的OpenHarmony SDK
4. 记下SDK安装路径，后续Kuikly项目配置可能需要

4. Kuikly项目配置

4.1 创建Kuikly项目

通过Kuikly插件可以快速创建支持OpenHarmony的项目：

1. 在Android Studio中，选择"File" → “New” → “New Project”

2. 在模板选择界面，找到并选择"Kuikly Project"模板
   

3. 按照向导填写项目信息，包括项目名称、包名等
   

4. 完成创建过程

   

5.稍后Gradle会自动下载依赖(可能会因为网络原因构建不成功)

4.2 配置Gradle环境

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

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

切换方式：

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

[图片占位符：Gradle版本设置界面]

如果Gradle版本低于7.4.1，需要在根目录的setting.gradle.kts文件中添加以下配置：

enableFeaturePreview("VERSION_CATALOGS")

4.3 忽略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)
}

5. Windows平台OpenHarmony编译配置

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

5.1 环境配置

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

1. 打开系统属性 → 高级系统设置 → 环境变量
2. 新建系统变量：
   • 变量名：OHOS_SDK_HOME
   • 变量值：D:\Program Files\DevEco Studio\sdk\default\openharmony（请替换为你的实际安装路径）
3. 确保该路径下包含OpenHarmony SDK

5.2 配置Kuikly OpenHarmony编译环境

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

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

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

pluginManagement {
    repositories {
        // 定制版kotlin工具链
        maven {
            url = uri("https://mirrors.tencent.com/nexus/repository/maven-tencent/")
        }
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    plugins {
        kotlin("android").version("2.0.21-KBA-010").apply(false)
        kotlin("multiplatform").version("2.0.21-KBA-010").apply(false)
        // 其他插件配置
    }
}

3. 编译命令：

./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

[图片占位符：OpenHarmony Gradle配置界面]

方式2：统一编译链形式

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

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

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

2. 修改Kotlin版本：

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

3. 在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")
        }
    }
}

4. 添加OpenHarmony构建目标：

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

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

5.3 Windows平台编译步骤

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

Step 1：编译OpenHarmony跨端产物

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

1. 打开Android Studio的Terminal
2. 执行编译命令：

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

3. 将生成的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/目录

[编译产物拷贝示意图]

Step 2：在DevEco Studio中编译OpenHarmony APP

1. 使用DevEco Studio打开OpenHarmony项目
2. 确保已正确配置so文件和头文件的路径
3. 点击"Run"按钮编译并运行OpenHarmony应用
4. 运行展示

！！！ Windows平台无法使用模拟器运行

5.4 自动化编译配置（可选）

为了简化编译流程，可以使用Kuikly Hvigor插件实现自动编译和拷贝：

1. 在OpenHarmony项目的根目录下创建或修改.npmrc文件：

registry=https://registry.npmjs.org/

2. 修改hvigor/hvigor-config.json5文件：

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

3. 在OpenHarmony项目的local.properties中配置：

# kuiklyCompilePlugin
# REQUIRED Parameters
kuikly.projectPath=你的Kuikly项目根路径
kuikly.moduleName=shared
kuikly.ohosGradleSettings=settings.ohos.gradle
# OPTIONAL Parameters
kuikly.soPath=entry/libs/arm64-v8a
kuikly.headerPath=entry/src/main/cpp
kuikly.compilePluginEnabled=true

4. 在entry/hvigorfile.ts中启用插件：

import { kuiklyCompilePlugin } from 'kuikly-ohos-compile-plugin';
export default {
    plugins: [kuiklyCompilePlugin()]
}

配置完成后，每次在DevEco Studio中构建项目时，插件会自动编译Kuikly产物并复制到正确位置。

6. 常见问题解决

6.1 Gradle依赖安装失败

如果在构建项目时遇到Gradle依赖安装失败的问题，可能是由于网络原因或版本不匹配导致。解决方法：

1. 确认Gradle版本为7.5.1
2. 检查项目中的Gradle配置是否正确
3. 尝试清理Gradle缓存：File → Invalidate Caches / Restart
4. 在终端执行：gradlew clean build --refresh-dependencies

[图片占位符：Gradle错误示例]

6.2 OpenHarmony模块无法识别

如果项目无法正确识别OpenHarmony模块，可能需要手动配置路径：

1. 确保DevEco Studio已正确安装并配置
2. 在项目中找到local.properties文件
3. 添加OpenHarmony SDK路径配置：

   ohos.sdk.path=C\:\\Users\\[用户名]\\AppData\\Local\\Huawei\\Sdk
   

6.3 Kuikly插件功能异常

如果Kuikly插件功能异常，可以尝试以下解决方法：

1. 更新Kuikly插件到最新版本
2. 重启Android Studio
3. 检查插件兼容性，确保Android Studio版本符合要求
4. 重新安装插件

7. 验证开发环境

完成以上配置后，需要验证环境是否正确搭建：

1. 打开创建的Kuikly项目
2. 尝试构建项目：Build → Make Project
3. 如果构建成功，尝试运行OpenHarmony模块
4. 在DevEco Studio中打开OpenHarmony相关模块，确认可以正常编译运行

[图片占位符：成功构建项目界面]

8. Kuikly插件功能介绍

安装Kuikly插件后，可以获得以下实用功能：

• 新建Kuikly业务工程：一键生成Kuikly业务工程与Android/iOS/OpenHarmony App宿主工程，自动集成Kuikly依赖
• 新建Kuikly的ComposeView类：自动帮业务开发者生成组合组件的模板代码
• 新建Kuikly的Pager类：自动帮业务开发者生成Pager的模板代码

这些功能可以大大提高OpenHarmony应用的开发效率。

结语

在Windows平台上搭建Kuikly OpenHarmony开发环境虽然有一些特殊步骤，但按照本文的详细指南操作，开发者可以顺利配置完成。重点是正确配置JDK 17环境、安装必要的插件、设置Gradle版本，以及正确配置Windows平台的OpenHarmony编译环境。完成环境搭建后，开发者就可以充分利用Kuikly框架的优势，高效地开发跨平台应用，特别是OpenHarmony应用。

随着OpenHarmony生态的不断发展，掌握这一技能将为开发者带来更多机会。希望本文能帮助Windows平台的开发者顺利进入Kuikly OpenHarmony开发领域。

附录：参考资料

• Kuikly官方文档
• OpenHarmony官方文档
• Kotlin Multiplatform官方文档

---