先说结论在 Windows 上把 OpenHarmony 的跨平台 UI 框架 Kuikly 的模板工程跑通核心不是 Kuikly 有多复杂而是先把 DevEco Studio、OpenHarmony SDK、ohpm、hvigor 这一套工具链理顺。这篇文章是 KuiklyUI 系列的第一篇我把完整流程整理成可直接照着敲的步骤同时也解释每一步为什么要这么做。你不需要先懂底层渲染也不需要把 OpenHarmony 源码看完只要按下面的顺序走就能在 Windows 上完成环境搭建、创建模板工程、用脚本编译出 HAP然后安装到开发板或模拟器上看效果。适合刚接触 OpenHarmony、又不想被工具链劝退的开发者也适合已经在用 ArkUI 但想切入跨平台方案的团队。1. KuiklyUI 这套框架到底解决什么问题1.1 OpenHarmony 应用开发为什么要用跨平台框架OpenHarmony 虽然生态起步晚但开发理念很现代ArkTS ArkUI 声明式写法的效率并不低。问题是你写出来的页面代码基本只能在 OpenHarmony 系设备上跑。如果是个人开发者或小团队手头还可能有 Flutter、React Native 甚至原生 Android 的业务这时候就面临两套甚至三套 UI 代码的维护成本。Kuikly 走的是“一套代码、多端编译”的路线你用类似声明式组合的写法描述界面框架层把这份描述转换成目标平台的原生组件。开发和调试时在 OpenHarmony 上跑未来需要迁移到其他平台时业务层的界面描述可以尽量复用。这和 Flutter 的思路相似但 Kuikly 更贴近 TypeScript / ArkTS 技术栈对 OpenHarmony 原生能力如元服务、分布式软总线的适配路径天然更顺。1.2 Kuikly 与 ArkUI、原生 ArkTS 开发的差异很多刚开始的朋友会问我不直接用 ArkUI 写非要套一层 Kuikly不是徒增复杂度吗我的理解是分场景看。如果你的团队只做 OpenHarmony 单端ArkUI 足够没必要引入框架。但如果你有“先跑通 OpenHarmony 业务后续还要复用代码到别处”的诉求Kuikly 的价值就出来了。它把“页面结构”从具体平台解耦你在代码里写的是一个组件树由 Kuikly 负责把它映射到 OpenHarmony 的 ArkUI 组件上。换句话说Kuikly 是站在 ArkUI 之上的一层框架而不是替代 ArkUI。这种做法带来的好处是业务层不绑死某一个 API 版本。OpenHarmony 更新快接口偶有调整但 Kuikly 框架会帮你做一层兼容。代价则是遇到框架没覆盖的犄角旮旯时你还是得回到 ArkUI 写补丁。2. Windows 主机上的 OpenHarmony 开发环境怎么配2.1 硬件和系统底限OpenHarmony 开发不挑机器但 Windows 平台有几个基本要求需要先确认。CPU 建议 i5 以上内存至少 16GB。如果你只写 UI 模板工程8GB 也能跑只是 DevEco Studio 和模拟器同时开着会比较吃力。磁盘建议预留 40GB 以上SDK、HarmonyOS 镜像、模拟器文件都挺占空间。系统方面Windows 10 1809 及以上的 64 位系统都可以Windows 11 更是没问题。这里要注意OpenHarmony 的命令行工具和一些调试驱动对系统的完整性要求比较高尽量不要用精简版、Ghost 版系统否则后面可能出现千奇百怪的驱动问题。2.2 安装 DevEco Studio 与 OpenHarmony SDK环境搭建绕不开 DevEco Studio它其实是 IntelliJ IDEA 的定制版内置了 ArkTS 语法支持、预览器、SDK 管理和 hdc 等工具。下载地址直接去 OpenHarmony 开发者官网或者华为开发者联盟找“DevEco Studio”安装包Windows 版是 exe 安装器。安装时不要一路“下一步”到底有个关键选项是选择组件。我一般建议把以下三项都勾上DevEco Studio 主程序OpenHarmony SDKohpm 包管理器安装完成后第一次启动向导会引导你下载和安装 SDK。OpenHarmony SDK 是按 API 版本区分的比如 API 9、API 10、API 11。Kuikly 模板工程通常要求 API 9 以上我目前实践用的是 API 10兼容性和功能平衡得比较好。勾选版本时不需要贪多装一个当前模板要求的最低版本即可装太多反而会让环境变量和编译器版本匹配变得混乱。SDK 默认安装位置一般在C:\Users\你的用户名\AppData\Local\OpenHarmony\Sdk也有可能在 DevEco Studio 安装目录下。这个路径后面配置命令行工具时要用到建议先在设置里看一下实际的 SDK 根目录。2.3 命令行工具与全局变量Node.js、ohpm、hvigorw很多人以为在 IDE 里点一下 Build 就能编译为什么还要搞命令行因为后续的自动化、持续集成、批量出包都离不开命令行。而且命令行能直接看到编译日志排查问题比 IDE 里一闪而过的错误框高效得多。在 Windows 上命令行工具链入口主要有三个Node.jsDevEco Studio 自带的构建系统 hvigor 基于 Node.js 运行建议使用 18 或 20 LTS 版本。ohpmOpenHarmony 的包管理器类似 npm负责下载依赖库。hvigorw项目级构建脚本负责编译打包。如果你在安装 DevEco Studio 时勾选了 ohpm它一般会被放到 SDK 的toolchains目录里。为了在任意终端都能直接使用我建议手动配置系统环境变量。具体做法打开“系统属性 - 环境变量”新建系统变量DEVECO_SDK_HOME值填 OpenHarmony SDK 根目录在Path中追加%DEVECO_SDK_HOME%\toolchains确认 Node.js 已经加入Path命令行输入node -v能输出版本号。配置好后分别打开一个新的终端窗口验证这几个命令node -v ohpm -v hvigorw -v注意hvigorw -v需要在某个 OpenHarmony 工程目录里执行才会有效因为它读取的是项目里的 hvigor 配置。如果你现在还没工程先到下一步创建不急着验证。2.4 建议先跑通一个 Hello World 再上 Kuikly在拉 Kuikly 模板之前我强烈建议你先用 DevEco Studio 创建一个原生 ArkTS 空工程跑通一次“创建 - 编译 - 预览/安装”的全链路。这不是浪费时间而是把“环境问题”和“框架问题”分开。空工程跑通了说明 Node.js、SDK、签名、模拟器/真机连接这一整套基础设施是健康的如果空工程都编译不过那你直接上 Kuikly 会遇到两个问题叠加排查起来很痛苦。新手最容易犯的错就是跳过 Hello World结果分不清报错来自 OpenHarmony 工具链还是来自 Kuikly。3. 创建 Kuikly 模板工程3.1 模板工程从哪里来Kuikly 的模板工程一般不在 DevEco Studio 的 New Project 向导里直接出现需要从开源仓库获取。最简单的做法是把 Kuikly 官方示例库里的模板目录下载下来或者直接git clone整个示例仓库到自己本机然后用 DevEco Studio 的“Open”功能打开其中的模板工程目录。如果你更想自己从头搭也可以先创建一个 Empty Ability 工程然后再往oh-package.json5里添加 Kuikly 相关依赖类似在 Flutter 工程里引入第三方包。但我个人还是建议先跑官方模板原因很简单模板里的hvigorfile.ts、build-profile.json5配置是官方验证过的环境组合相对可靠。自己手搓一份配置如果版本配错了一遍遍试错的时间成本远高于直接改几行模板代码。3.2 工程目录结构先认全模板工程下载后打开前后先别急着点 Build花五分钟把目录结构看明白。一个典型的 Kuikly 工程大致长这样my-kuikly-app/ ├─ AppScope/ # 应用级配置 │ ├─ app.json5 # 应用名称、包名、版本信息 │ └─ resources/ # 应用级资源 ├─ entry/ # 主模块 │ ├─ src/main/ │ │ ├─ ets/ # 源码目录 │ │ │ ├─ entryability/ # 应用生命周期入口 │ │ │ └─ pages/ # 页面 │ │ ├─ resources/ # 模块资源 │ │ └─ module.json5 # 模块配置 │ └─ build-profile.json5 # 模块编译配置 ├─ oh-package.json5 # 工程级依赖 ├─ build-profile.json5 # 工程级编译配置 ├─ hvigorfile.ts # hvigor 构建脚本入口 ├─ hvigorw # macOS/Linux 构建脚本 ├─ hvigorw.bat # Windows 构建脚本 └─ hvigor/这里的重点是hvigorw.bat。Windows 下的编译入口就是它文档里写./hvigorw是 macOS/Linux 的写法Windows 下要写成.\hvigorw.bat这是很多新手第一处卡壳的地方。3.3 关键配置文件的作用oh-package.json5相当于工程里的 package.json里面声明了依赖。Kuikly 模板里会有一行类似dependencies: { kuikly/core: ^x.y.z, kuikly/components: ^x.y.z }具体版本号以你拉取到的模板为准。当你修改了依赖后需要在工程目录里执行ohpm install重新同步依赖这一点和 npm 的流程一样。build-profile.json5则是给 hvigor 看的里面定义了签名配置、产品形态和模块列表。模板里通常默认配好了 debug 自动签名这意味着你本地编译的 HAP 可以直接安装到开发板或者模拟器上不用自己再去生成证书。到 Release 阶段才需要去配置正式的签名文件这块后续可以单独写一篇。4. 脚本编译流程从工程到 HAP4.1 hvigorw 命令的使用逻辑hvigor 是 OpenHarmony 工程的默认构建系统名字听起来像 Gradle设计思路也确实有点像通过任务、插件来完成清洁、编译、打包、签名等操作。hvigorw.bat是工程自带的 wrapper 脚本它会读取hvigor/hvigor-config.json5里的版本号自动选择合适的 hvigor 器来执行任务。常用任务不多记住这三个基本就够clean清理构建产物assembleHap编译并生成 HAP 包install有的模板支持直接安装到设备更多的时候我们会给命令追加参数来控制编译范围。OpenHarmony 的工程支持多模块、多产品比如一个应用有 entry、library 两个模块你想只编译 entry 模块就可以加--mode module -p moduleentrydefault这类参数。4.2 完整编译步骤演示假设你的 Kuikly 工程在D:\work\my-kuikly-app并且环境变量已经配置好。打开 PowerShell 或命令提示符先进入工程目录cd D:\work\my-kuikly-app第一步同步依赖ohpm install这一步会读取oh-package.json5把 Kuikly 相关依赖下载到本地。如果网络不稳定或者镜像源没配好很容易卡在这里。建议先执行一次 ohpm 配置ohpm config set registry https://ohpm.openharmony.cn/ohpm/把包管理器指向 OpenHarmony 官方镜像下载速度和成功率都会有明显改善。第二步执行编译.\hvigorw.bat assembleHap --mode module -p moduleentrydefault -p productdefault如果你用的是模板自带的签名配置编译产物会出现在entry/build/default/outputs/default/entry-default-signed.hap这个路径里的default是 product 名entry是模块名。如果你的工程结构不一样路径会相应调整可以打开entry/build/outputs目录直接看生成结果。第一次编译会比较慢因为 hvigor 需要下载依赖、初始化缓存再加上 Kuikly 框架层编译耗时可能在三到五分钟左右。后续增量编译会快很多。编译完成后可以用 hdc 工具把 HAP 安装到已连接的真机或模拟器。先看一下设备是否识别hdc list targets如果有设备执行安装hdc install entry/build/default/outputs/default/entry-default-signed.hap看到install success就说明整个链路已经通了。4.3 输出产物及验证HAP 就是 OpenHarmony 应用的可安装包类似 Android 的 APK。编译目录里通常会生成多个文件包括文件作用entry-default-signed.hap已签名包可直接安装entry-default-unsigned.hap未签名包一般用于发布前单独签名entry-default.app应用包常见于多 HAP 场景建议优先使用带signed的产物。如果你在编译日志里看到类似“scene config error”或者“hap not signed”的字样说明签名配置有问题先检查build-profile.json5里的 signingConfigs 字段。4.4 自定义编译脚本建议bat / PowerShell既然我们的文章主题是“脚本编译”那自然不能只在终端里敲一遍命令就完事最好把整个流程固化成一个脚本下次双击就能跑。下面是我在 Windows 上常用的一个 bat 脚本已经经过多台机器验证echo off setlocal set DEVECO_SDK_HOMEC:\Users\你的用户名\AppData\Local\OpenHarmony\Sdk set PATH%DEVECO_SDK_HOME%\toolchains;%PATH% cd /d D:\work\my-kuikly-app echo [STEP 1] ohpm install call ohpm install if errorlevel 1 ( echo [ERROR] ohpm install failed exit /b 1 ) echo [STEP 2] hvigorw assembleHap call .\hvigorw.bat assembleHap --mode module -p moduleentrydefault -p productdefault if errorlevel 1 ( echo [ERROR] build failed exit /b 1 ) echo [STEP 3] install to device hdc list targets nul 21 if errorlevel 1 ( echo [WARN] no device found, skip install exit /b 0 ) hdc install entry\build\default\outputs\default\entry-default-signed.hap echo [DONE] endlocal这段脚本做了三件事同步依赖、编译、安装设备。每步都检查错误码有失败就退出方便在 CI 管道里直接调用。PowerShell 用户也可以改写成.ps1脚本逻辑相同。要注意的是 bat 脚本的文件编码如果里面有中文保存为 GBK 或 UTF-8 with BOM 格式否则可能在旧版控制台乱码。5. 常见问题与排查实录5.1 常见问题速查表我在 Windows 上反复搭过好几轮环境也帮朋友排查过不少问题。下面的现象和解决方案是最常遇到的直接整理成表现象可能原因解决办法hvigorw不是内部或外部命令未进入工程目录或环境变量 PATH 没配好确认在工程根目录执行检查%DEVECO_SDK_HOME%\toolchains是否在 PATHohpm install卡住或超时默认源访问慢执行ohpm config set registry https://ohpm.openharmony.cn/ohpm/后重试编译报错Failed to find SDKDEVECO_SDK_HOME 指向错误打开 DevEco Studio 设置确认 SDK 实际路径HAP 安装失败error: device not foundhdc 服务未启动或设备未授权执行hdc kill、hdc start再hdc list targets确认编译时提示 API 版本不匹配工程要求的 API 版本与 SDK 不一致修改build-profile.json5中的compileSdkVersion和targetSdkVersionWindows 提示“禁止运行脚本”PowerShell 执行策略限制用命令提示符或执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned5.2 三个容易忽略的坑第一个坑是hdc 服务没重启。设备连上后偶尔会出现list targets能看到设备但install报错的情况多半是 hdc 服务进程状态异常。命令行里执行hdc kill再hdc start通常都能解决。这个操作很基础但很多人不知道。第二个坑是编译缓存冲突。如果你先开 DevEco Studio 构建过一次然后又用命令行构建偶尔会遇到一些诡异的“文件被占用”错误。Windows 下文件锁问题比 Linux 明显尤其是杀毒软件扫到构建目录时。遇到这类报错先关掉 IDE执行.\hvigorw.bat clean再重试构建。第三个坑是杀毒软件把 hvigorw 执行过程给拦了。Node.js 工程里大量的临时文件写入和子进程调度很容易触发 Windows Defender 或第三方杀毒的实时防护。如果频繁出现“编译到一半崩掉”的情况试着把工程目录加入杀毒软件白名单。这不是妥协Windows 下做开发环境本来就应该把开发目录排除掉。5.3 千万别忽视的 Windows 终端细节在 Windows 上执行脚本和 macOS 有很明显的差异。比如直接双击hvigorw.bat有时会闪退这不是脚本坏了而是工作目录不对。正确做法是先打开终端cd 到工程目录再敲.\hvigorw.bat。另外很多教程里写./hvigorw如果你在 PowerShell 里复制粘贴执行可能会提示“找不到命令”。这是 Windows 路径分隔符和执行前缀的差异不是工程问题。统一使用.\前缀会稳妥很多。还有一点PowerShell 默认的$PWD和命令提示符的cd行为略有不同如果你在脚本里使用了相对路径尽量用 pushd/popd 包裹避免中途把工作目录切丢。我的脚本里用cd /d强制指定盘符和目录就是这个原因。6. 从模板到项目落地的一点体会环境搭好之后我会建议你把 Kuikly 模板工程的目录结构和配置先抄一遍而不是直接动手改业务。原因很简单模板是官方调好的“基准线”在你还不熟悉 hvigor 和签名机制时任何改动都可能让编译行为偏移。我早期就是着急把工程改名、换包名结果改出一个编译不过的工程最后只能重新下载模板。如果你后面要对接持续集成Windows Agent 上大概率还需要再安装一份 DevEco Studio 的命令行工具并保证环境变量一致。这一点和本地开发的配置思路是相通的但要注意 CI Agent 的用户权限、代理网络和缓存目录往往更复杂。建议先把本地脚本跑稳定再迁移到 CI。我个人在实际操作中最深的体会是OpenHarmony 工具链久不久就更新一版SDK 版本一变旧的模板可能就要跟着调。所以每个 Kuikly 工程我都会记下它的 hvigor 版本、SDK 版本、API 级别形成一个小文档。以后工程报错先看这份版本组合再排查代码能省大量时间。这一篇的核心流程已经全部跑通Windows 装环境、创建 Kuikly 模板工程、用 hvigorw 脚本编译 HAP、安装到设备。下一篇我会继续写 Kuikly 的页面结构拆解和自定义组件封装到时候我们用一个真实页面来对比 ArkUI 和 Kuikly 的写法差异。