前言

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

在全场景智能终端快速普及的今天，OpenHarmony 开源鸿蒙操作系统已经成为国内物联网、移动终端、智能家居、智慧出行等领域的重要系统底座。随着设备种类不断丰富，应用生态不断完善，越来越多的开发者、在校学生、技术爱好者开始进入鸿蒙应用开发领域。与此同时，能够实现一套代码、多端运行的跨平台开发框架，也成为开发者提升效率、降低维护成本的首选方案。

Kuikly 作为一款轻量、高效、简洁易用的跨平台 UI 框架，凭借学习成本低、运行性能高、双端兼容性强等特点，越来越多地被用于鸿蒙与 Android 双平台应用开发，尤其适合在校学生、入门开发者、课程设计与毕业设计等场景使用。

对于绝大多数初学者而言，进入鸿蒙开发遇到的第一个难点往往不是代码编写，而是开发环境搭建。很多教程内容繁杂、工具繁多、步骤跳跃、依赖复杂，让不少新手望而却步。为了让零基础开发者能够真正做到“照着做就能成功”，本文提供一套极度精简、稳定可靠、无多余依赖的环境搭建方案。

本篇文章全程不使用 Git、不使用 Node.js、不使用 Python、不使用命令行复杂操作，只依靠两款官方 IDE 工具：

DevEco Studio + Android Studio，

分别完成 Kuikly 插件安装、环境配置、模板工程导入、项目编译、运行调试、打包输出等整套流程。全文内容详细、步骤完整、语言通俗、不使用晦涩专业术语，每一步操作都有明确说明，同时预留图片占位，方便插入实操截图，可直接作为技术博客、教学文档、培训教程、实验指导书使用。

通过本文的学习，你将能够独立完成：

• DevEco Studio 安装与 OpenHarmony SDK 配置
• Android Studio 安装与基础配置
• 双 IDE 中 Kuikly 插件的安装与启用
• 模板工程下载、解压、导入
• 项目结构理解与 HMIL 界面文件认识
• 双平台项目运行、调试、打包
• 常见环境问题排查与解决

一、开发环境基本要求

在开始安装工具与配置环境之前，我们首先明确电脑配置要求，确保环境能够正常安装、运行、编译，避免因硬件或系统问题导致报错。

1.1 操作系统要求

• 支持 Windows 10 64 位 专业版、家庭版、企业版
• 支持 Windows 11 64 位 专业版、家庭版、企业版
• 必须为 64 位操作系统，不支持 32 位系统
• 不支持 Windows 7、Windows 8 等低版本系统

操作系统是整个开发环境的基础，只有满足系统要求，后续的 IDE、SDK、插件才能正常安装与运行。对于仍在使用旧版操作系统的用户，建议先升级系统，再进行环境搭建。

1.2 硬件配置要求

• 运行内存：最低 8GB，推荐 16GB 及以上
• 硬盘空间：至少预留 30GB 可用空间
• 处理器：支持 Intel VT-x / AMD-V 硬件虚拟化技术（用于运行模拟器）
• 磁盘类型：SSD 固态硬盘最佳，机械硬盘可正常使用但速度较慢
• 屏幕分辨率：建议 1920×1080 及以上，便于 IDE 界面操作

开发工具与模拟器对内存消耗较大，内存不足会导致 IDE 卡顿、编译缓慢、模拟器无法启动等问题。因此，尽量满足推荐配置，能够显著提升开发体验。

1.3 路径规范要求（非常重要）

为避免环境配置、项目编译、模拟器运行出现未知错误，所有安装路径与项目路径必须遵守以下规则：

• 路径中不允许出现中文
• 路径中不允许出现空格
• 路径中不允许出现特殊符号，如 @、#、￥、&、空格等

正确路径示例：

D:\Dev\DevEcoStudio D:\Dev\AndroidStudio D:\Dev\OpenHarmonySDK D:\Work\KuiklyDemo

错误路径示例：

D:\软件\DevEco Studio D:\项目\Kuikly 演示项目 C:\Users\张三\Desktop\KuiklyProject

严格遵守路径规范，是环境搭建一次成功的关键。很多新手搭建失败，并非步骤错误，而是路径中包含中文或空格，导致工具无法正常识别。

1.4 网络要求

• 能够正常访问互联网
• 能够正常下载 IDE 安装包、SDK 资源、插件资源
• 下载过程保持网络稳定，不要断开或切换代理

SDK 与插件下载过程较大，网络不稳定可能导致下载中断、文件损坏，进而引发安装失败。因此，在开始环境搭建前，确保网络稳定可用。

二、必备开发工具说明

本文搭建 Kuikly 跨平台开发环境，只需要安装两个官方 IDE，除此之外不安装任何多余工具：

1. DevEco Studio

OpenHarmony 官方集成开发环境，用于开发、编译、运行、打包 OpenHarmony 应用。

1. Android Studio

Android 官方集成开发环境，用于开发、编译、运行、打包 Android 版本应用。

Kuikly 框架以插件形式分别运行在两个 IDE 中，不需要额外配置运行环境、脚本工具或第三方依赖。这种方式简洁、稳定、易于维护，非常适合新手入门。

三、安装 DevEco Studio 与 OpenHarmony SDK

DevEco Studio 是 Kuikly 在 OpenHarmony 平台的开发载体，必须正确安装并配置 SDK。

3.1 DevEco Studio 简介

DevEco Studio 提供代码编辑、项目管理、界面预览、编译构建、模拟器运行、调试、打包发布等一站式开发能力，是 OpenHarmony 生态唯一官方 IDE，也是 Kuikly 框架的指定开发工具。其界面风格与 Android Studio 相似，学习成本低，上手速度快。

3.2 下载 DevEco Studio

1. 打开浏览器，进入华为开发者联盟官网 https://developer.huawei.com/consumer/cn/
2. 进入 DevEco Studio 产品页面
3. 选择 Windows 系统版本，下载最新稳定版安装包
4. 等待安装包下载完成

3.3 安装 DevEco Studio

1. 双击下载完成的安装程序
2. 选择安装语言，默认为 English，点击 Next
3. 阅读许可协议，点击 I Agree
4. 设置安装路径，建议使用：

D:\Dev\DevEcoStudio

1. 点击 Next
2. 在组件选择界面，保持默认全部勾选
3. 点击 Next
4. 在开始菜单设置界面，保持默认，点击 Next
5. 点击 Install 开始安装
6. 等待安装进度完成
7. 勾选 Run DevEco Studio
8. 点击 Finish 完成安装

3.4 首次启动与 SDK 配置

1. 首次启动弹出导入配置界面，选择 Do not import settings
2. 点击 OK
3. 进入用户协议界面，勾选同意所有协议
4. 点击 Continue
5. 进入 SDK 配置界面
6. 设置 OpenHarmony SDK 安装路径，建议：

D:\Dev\OpenHarmonySDK

1. 点击 Next
2. 确认组件下载界面，保持默认选择
3. 点击 Next
4. 同意 SDK 许可协议，开始下载
5. 等待下载与解压完成（时间较长，耐心等待）
6. 下载完成后，点击 Finish 进入 DevEco Studio 主界面

至此，DevEco Studio 与 OpenHarmony SDK 安装配置完成。

四、安装 Android Studio

Android Studio 用于开发、编译、运行 Android 版本的 Kuikly 项目。

4.1 下载 Android Studio

1. 打开浏览器，进入 Android 开发者官网  下载 Android Studio 和应用工具 - Android 开发者  |  Android Developershttps://developer.android.com/studio?hl=zh-cn
2. 下载 Windows 稳定版 Android Studio
3. 等待安装包下载完成

4.2 安装 Android Studio

1. 双击安装程序
2. 点击 Next
3. 组件选择界面保持默认
4. 设置安装路径，建议：

D:\Dev\AndroidStudio

1. 点击 Next
2. 开始菜单设置保持默认
3. 点击 Install
4. 等待安装完成
5. 勾选 Start Android Studio
6. 点击 Finish

4.3 首次启动与Kuikly配置

1. 首次启动选择 Do not import settings
2. 点击 OK
3. 选择 Standard 标准安装模式
4. 选择主题，点击 Next
5. 确认 Kuikly组件，点击 Next
6. 同意协议，开始下载
7. 等待 Kuikly下载完成
8. 点击 Finish 进入主界面

Android Studio 基础环境安装完成。

4.4安装 Kotlin 及 Kotlin MultiPlatform 插件

在进行 Kuikly 项目开发前，需要在 Android Studio 中安装必要的 Kotlin 相关插件，具体步骤如下：

1. 打开 Android Studio

启动你的 Android Studio 开发环境。

2. 进入插件市场

在顶部菜单栏依次点击：

File → Settings（Windows/Linux）或 Android Studio → Preferences（macOS）

在弹出的设置窗口中，选择左侧的 Plugins 选项，然后切换到 Marketplace 标签页。

3. 搜索并安装插件

在 Marketplace 的搜索框中输入 Kotlin，在搜索结果中找到并安装以下两个核心插件：

• Kotlin：新版 Android Studio 通常已内置此插件，如未安装请手动安装。
• Kotlin MultiPlatform Mobile：用于支持跨平台移动开发的核心插件。

安装完成后，重启 Android Studio 使插件生效。

五、安装JDK17

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

1. 访问 Oracle JDK 下载界面或 OpenJDK 网站下载 JDK 17

[Oracle JDK 下载]

1. 打开 Oracle 官网（Java 下载 |神谕)点击顶部导航栏的 “产品”。
2. 在下拉菜单中找到 “硬件和软件” 分类，点击 “Java”。
3. 在 Java 页面中，点击 “下载 Java” 按钮。
4. 在 Java 下载页面，向下滚动找到 “Java 17” 选项卡。
5. 在“Java SE Development Kit 17.0.18 downloads”区域，选择 “Windows” 平台。
6. 选择 “x64 Installer”（.exe 文件）进行下载。

[OpenJDK 下载]（推荐，免费且开源）

1. 打开 Adoptium 官网（https://adoptium.net），点击 “下载 Temurin”。
2. 在版本选择中，选择 “JDK 17 (LTS)”。
3. 在平台选择中，选择 “Windows”。
4. 选择对应的安装包（如 .msi 或 .zip）进行下载。

2. 安装JDK 17 到本地目录

运行下载的安装程序，按照向导完成安装，记住安装路径，例如：

C:\Program Files\Java\jdk-17

3. 配置环境变量

1. 右键点击 “此电脑” → 选择 “属性” → 点击 “高级系统设置” → 点击 “环境变量”。
2. 在 “系统变量” 区域：
   • 点击 “新建”，创建一个新的系统变量：
     • 变量名：JAVA_HOME
     • 变量值：你的 JDK 安装路径，例如 C:\Program Files\Java\jdk-17
   • 找到系统变量中的 Path，点击 “编辑”：
     • 点击 “新建”，添加一条新的路径：%JAVA_HOME%\bin
3. 依次点击所有窗口的 “确定”，保存配置。

4. 验证配置是否成功

打开 CMD 或 PowerShell，分别输入以下命令：

java -version javac -version

如果命令返回类似以下信息，说明配置成功：

java version "17.0.18" 2024-01-16 LTS Java(TM) SE Runtime Environment (build 17.0.18+9-LTS-257) Java HotSpot(TM) 64-Bit Server VM (build 17.0.18+9-LTS-257, mixed mode) javac 17.0.18

六、在 Android Studio 中安装 Kuikly 插件

与 DevEco Studio 相同，Android Studio 也需要安装 Kuikly 插件。

6.1 打开插件面板

1. 点击顶部菜单栏 File
2. 选择 Settings
3. 找到 Plugins

6.2 安装 Kuikly 插件

1. 在搜索框输入：

Kuikly

1. 找到官方插件
2. 点击 Install
3. 安装完成后重启 Android Studio

6.3 插件安装成功

重启后，Android Studio 可正常识别 Kuikly 项目结构与代码。

七、获取 Kuikly 模板工程（无需 Git）

为降低新手入门难度，直接使用 Kuikly 官方模板工程，不使用 Git，直接下载 ZIP 压缩包。

7.1 下载模板 ZIP

1. 打开浏览器 https://gitcode.com/Tencent-TDS/KuiklyUI/tree/fix/2.4.2
2. 进入 Kuikly 官方模板仓库页面
3. 点击 Code
4. 选择 Download ZIP
5. 等待压缩包下载完成

7.2 解压模板工程

1. 找到下载的 ZIP 文件
2. 右键解压到英文路径，例如：

D:\Work\KuiklyTemplate

解压后得到完整可运行项目。

八、在 DevEco Studio 中导入 Kuikly 模板工程

8.1 导入项目

1. 打开 DevEco Studio
2. 点击 Open
3. 选择解压后的 Kuikly 项目文件夹
4. 点击 OK 开始导入

8.2 配置 local.properties

打开项目中的 local.properties 文件，写入本机 SDK 路径：

sdk.dir=D:/Dev/OpenHarmonySDK

8.3 等待项目同步

IDE 自动进行 Gradle 同步、依赖加载、索引构建。

同步完成后，无红色报错、无异常提示，表示导入成功。

九、在 Android Studio 中导入 Kuikly 模板工程

9.1 打开项目

1. 打开 Android Studio
2. 点击 Open
3. 选择同一个 Kuikly 项目文件夹
4. 点击 OK

9.2 自动同步配置

Android Studio 自动识别项目结构，完成 Gradle 同步、Android SDK 配置、依赖下载。

同步完成后，项目可直接编译运行。

十、Kuikly 项目目录结构与 HMIL 介绍

10.1 项目目录结构

Kuikly 是跨平台框架，项目结构清晰，一套代码双端共用：

• common：双端共享代码（业务逻辑、工具、公共组件）
• ohos：OpenHarmony 平台相关代码
• android：Android 平台相关代码
• build.gradle：项目构建配置
• local.properties：本地环境配置

开发者只需要在 common 目录编写核心逻辑与界面，双端即可自动运行，无需重复开发。

10.2 HMIL 是什么

HMIL 全称 Harmony Markup Language，是 OpenHarmony 专用的界面布局文件，后缀为 .hmil。

作用：

• 定义页面结构
• 摆放组件：文本、按钮、图片、输入框、列表等
• 设置组件位置、大小、样式

对应关系：

• Android 界面 → .xml
• 鸿蒙界面 → .hmil

10.3 HMIL 简单示例

<Column>     <Text>Hello OpenHarmony</Text>     <Button>点击测试</Button> </Column>

HMIL 是鸿蒙开发最基础的界面文件，也是 Kuikly 框架中编写界面的核心方式。

十一、DevEco Studio 运行 OpenHarmony 版本

11.1 启动 OpenHarmony 模拟器

1. 点击 DevEco Studio 右上角 Device Manager
2. 选择可用模拟器设备
3. 点击启动图标
4. 等待模拟器开机完成

11.2 运行项目

1. 在运行配置中选择 ohos 或 entry 模块
2. 点击运行按钮（绿色三角）
3. IDE 自动编译、安装、启动应用
4. 模拟器中显示 Kuikly 模板界面，表示运行成功

运行成功的界面

十二、Android Studio 运行 Android 版本

12.1 启动 Android 模拟器

1. 点击 Android Studio 右上角 Device Manager
2. 选择手机模拟器
3. 启动并等待开机完成

12.2 运行项目

1. 选择运行模块
2. 点击运行按钮
3. 自动安装并启动 App
4. 界面正常显示表示运行成功

十三、编译生成 HAP 与 APK 安装包

13.1 编译 OpenHarmony HAP 包

1. 在 DevEco Studio 中
2. 点击顶部菜单 Build → Build Hap(s)
3. 等待编译完成
4. 在以下目录获取 HAP 安装包：

ohos/build/outputs/default/

13.2 编译 Android APK 包

1. 在 Android Studio 中
2. 点击 Build → Build APK
3. 等待打包完成
4. 在以下目录获取 APK 安装包：

android/build/outputs/apk/

十四、新手常见问题与解决方案

14.1 SDK 路径找不到

解决：检查 local.properties 路径是否正确，统一使用 / 符号。

14.2 Kuikly 插件不生效

解决：重启 IDE，重新安装插件。

14.3 项目同步失败

解决：点击 Clean Project → Rebuild Project。

14.4 模拟器无法启动

解决：进入电脑 BIOS 开启虚拟化，关闭杀毒软件。

14.5 运行白屏、闪退

解决：重新编译项目，检查依赖是否完整。

14.6 双端代码不同步

解决：只在 common 模块编写界面与逻辑，避免双端重复开发。

十五、全文总结

本文完整、详细、零基础可落地介绍了 Windows 平台 Kuikly OpenHarmony + Android 双平台开发环境搭建 的全部流程，核心内容包括：

• 系统与硬件要求
• DevEco Studio 安装与 OpenHarmony SDK 配置
• DevEco Studio 安装 Kuikly 插件
• Android Studio 安装与配置
• Android Studio 安装 Kuikly 插件
• 下载并解压 Kuikly 模板工程
• 双 IDE 导入项目、配置环境、同步编译
• HMIL 界面文件基础认识
• 双平台运行、调试、打包
• 新手常见问题解决方案

整套环境不依赖 Git、Node.js、Python 等任何多余工具，配置简单、步骤清晰、稳定性高，是目前最适合初学者的 Kuikly 跨平台开发环境搭建方案。

完成本文所有步骤后，你已经具备独立开发 Android + OpenHarmony 双端兼容应用 的能力，可以开始进行界面开发、逻辑编写、功能实现、打包发布等完整开发流程。