本文从下载 Qt 在线安装器开始,一步步在 Qt Creator 里配出能 configure → 编译 → 打 HAP 的鸿蒙开发环境,并把官方 wiki 没讲清的 Kit 配置坑全列出来。适用于 Windows + Qt 6.12.0 Beta2 + HarmonyOS arm64-v8a + Qt Creator。

官方参考:Qt for HarmonyOS development with 6.12.0 Beta2 — Windows。官方 wiki 只给了命令行流程,Qt Creator 的 Kit 配置有几个一抄就踩的坑,本文补全。

---

目录

1. 下载与安装
2. 路径清单
3. 环境变量
4. Qt Creator Kit 配置(核心)
5. 构建
6. 打 HAP:harmonydeployqt6
7. 踩坑速查(全实测)
8. 用官方 demo 验证
9. 总结

---

一、下载与安装

1.1 Qt 6.12 在线安装器

1. 到 https://www.qt.io/download 注册 Qt 账号,下载 Qt Online Installer(Windows 版 qt-online-installer-windows-x64-*.exe)。

2. 运行安装器,登录账号,选择安装路径(本文以 C:\Qt\6.12.0 为例,按你的实际改)。

3. 在组件选择页,勾选:
   

   组件	路径下的勾选项	为什么需要
   Qt for Development Qt 6.12.0	HarmonyOS	鸿蒙目标 Qt 库(必选)
   Developer and Designer Tools	CMake、Ninja	构建(如果有的话也可用系统自带的，后续发现没有可以单独再次下载)
   可选	Qt Debug Informatin Files	可以看到Qt框架内部的调试信息，一般搭配Qt源码(Sources)使用

其中调试信息可以不勾选，减少下载包的大小：

4. 一路 Next 完成安装。装完后 C:\Qt\6.12.0\ 下应有 harmonyos_arm64_v8a\、mingw_64\、Tools\CMake_64\、Examples\Qt-6.12.0\ 等。

1.2 DevEco Studio(鸿蒙 SDK + 打包工具链)

1. 到 https://developer.huawei.com/consumer/cn/deveco-studio/ 下载 DevEco Studio。
2. ⚠️ 装到无空格路径!官方 wiki 明确警告"路径含空格会导致构建失败"。本文以 C:\DevEcoStudio 为例(不要装到默认的 C:\Program Files\Huawei\DevEco Studio,空格会埋雷)。 (如果有空格的话需要使用"~"的方式去掉空格，但是比较麻烦）
3. 首次启动 DevEco,让它把 HarmonyOS SDK 装好。native 工具链在 C:\DevEcoStudio\sdk\default\openharmony\native\(含 llvm\bin\clang++.exe、sysroot\、build\cmake\ohos.toolchain.cmake)。

装无空格路径能一次性规避后面"空格路径"类的坑(短路径/quote 炸裂等),强烈推荐。

---

二、路径清单(本文示例值)

以下路径按你实际安装位置调整。本文示例:Qt 装在 C:\Qt\6.12.0,DevEco 装在 C:\DevEcoStudio。

项	示例路径	用途
Qt 安装根	C:\Qt\6.12.0	—
Qt 鸿蒙目标	C:\Qt\6.12.0\harmonyos_arm64_v8a	CMAKE_PREFIX_PATH
Qt host 构建	C:\Qt\6.12.0\mingw_64	QT_HOST_PATH;harmonydeployqt6.exe 在此
qt.toolchain.cmake	C:\Qt\6.12.0\harmonyos_arm64_v8a\lib\cmake\Qt6\qt.toolchain.cmake	CMAKE_TOOLCHAIN_FILE
DevEco 根	C:\DevEcoStudio	DEVECO_SDK_HOME(无空格)
OHOS native SDK	C:\DevEcoStudio\sdk\default\openharmony\native	OHOS_SDK_NATIVE,含 llvm/sysroot
OHOS clang++	C:\DevEcoStudio\sdk\default\openharmony\native\llvm\bin\clang++.exe	Kit C++ 编译器
ohos.toolchain.cmake	C:\DevEcoStudio\sdk\default\openharmony\native\build\cmake\ohos.toolchain.cmake	QT_CHAINLOAD_TOOLCHAIN_FILE
hvigorw.bat	C:\DevEcoStudio\tools\hvigor\bin\hvigorw.bat	HAP 打包(QT_HARMONYOS_HVIGOR)
node	C:\DevEcoStudio\tools\node	NODE_HOME
java	C:\DevEcoStudio\jbr\bin	JAVA_HOME
harmonydeployqt6.exe	C:\Qt\6.12.0\mingw_64\bin\harmonydeployqt6.exe	host 工具,不在鸿蒙目标里

---

三、环境变量(给 harmonydeployqt6 / hvigor 用)

在 系统环境变量 或 Qt Creator Kit 的 Environment 里设:

NODE_HOME=C:\DevEcoStudio\tools\node
JAVA_HOME=C:\DevEcoStudio\jbr\bin
DEVECO_SDK_HOME=C:\DevEcoStudio
QT_HARMONYOS_HVIGOR=C:\DevEcoStudio\tools\hvigor\bin\hvigorw.bat
PATH 追加: C:\Windows\System32;C:\DevEcoStudio\tools\node;C:\DevEcoStudio\jbr\bin;C:\DevEcoStudio\tools\hvigor\bin;C:\DevEcoStudio\tools\ohpm\bin

⚠️ PATH 一定要带上 C:\Windows\System32!否则后面打 HAP 时 ArkTS 编译器 es2abc 会报 spawn cmd.exe ENOENT(见 踩坑3)。如果你在 Kit 的 Environment 里直接 PATH=... 覆盖了系统 PATH(而不是追加),会把 System32 冲掉,这是最常见的翻车点。

QT_HARMONYOS_HVIGOR 设了之后,harmonydeployqt6 调用时可以不传 --hvigor 参数,它会自动读这个环境变量。

---

四、Qt Creator Kit 配置(核心)

打开 Qt Creator → Edit → Preferences → Kits,新建或编辑一个 Kit(比如叫 HarmonyOS),逐项设置:

4.1 编译器

Kit 的 C/C++ 编译器指向 DevEco 自带的 OHOS clang:

• C++ 编译器:C:\DevEcoStudio\sdk\default\openharmony\native\llvm\bin\clang++.exe
• C 编译器:C:\DevEcoStudio\sdk\default\openharmony\native\llvm\bin\clang.exe

4.2 CMake 初始配置(最易踩坑,重点看)

Kit → CMake → Initial Configuration(初始 CMake 配置)。先清空全部现有条目(避免重复/笔误/带引号旧条目),再粘贴下面这一份:

-DCMAKE_CXX_COMPILER:FILEPATH=%{Compiler:Executable:Cxx}
-DCMAKE_C_COMPILER:FILEPATH=%{Compiler:Executable:C}
-DCMAKE_PREFIX_PATH:PATH=%{Qt:QT_INSTALL_PREFIX}
-DCMAKE_GENERATOR:STRING=Ninja
-DCMAKE_TOOLCHAIN_FILE:FILEPATH=C:/Qt/6.12.0/harmonyos_arm64_v8a/lib/cmake/Qt6/qt.toolchain.cmake
-DQT_CHAINLOAD_TOOLCHAIN_FILE:FILEPATH=C:/DevEcoStudio/sdk/default/openharmony/native/build/cmake/ohos.toolchain.cmake
-DOHOS_SDK_NATIVE:PATH=C:/DevEcoStudio/sdk/default/openharmony/native
-DOHOS_ARCH:STRING=arm64-v8a
-DQT_HOST_PATH:PATH=C:/Qt/6.12.0/mingw_64
-DQT_QMAKE_EXECUTABLE:FILEPATH=%{Qt:qmakeExecutable}

%{Compiler:Executable:Cxx}、%{Qt:QT_INSTALL_PREFIX}、%{Qt:qmakeExecutable} 是 Qt Creator 宏,Kit 上下文里自动展开。OHOS SDK 路径没有对应的 QtC 宏,所以写死(路径按你实际改)。

三条铁律(踩坑总结,务必遵守)

1. 值不带首尾 " + 用正确类型(FILEPATH/PATH/STRING),不要 :UNINITIALIZED。
   反例:把官方 wiki 命令行的 -DCMAKE_TOOLCHAIN_FILE="..."(带 :UNINITIALIZED 和引号)整行粘进配置表 → Qt Creator 会写成 ""value"" → cmake 收到首尾带字面 " 的路径 → if(EXISTS) 判不存在 → 报 Could not find toolchain file(文件其实存在)。详见 踩坑1。

2. QT_CHAINLOAD_TOOLCHAIN_FILE 必须在、且指向真实 Windows 路径。
   它指向 OHOS 的 ohos.toolchain.cmake,负责设定目标三元组 arm64-ohos、sysroot、链接参数。缺了它,Qt 的 qt.toolchain.cmake 会回退一个 Qt 编译时烤进去的 Linux 默认路径(/opt/harmonyos/...,不存在)→ OHOS 工具链没加载 → cmake 把 clang++ 当成普通 host 编译器 → 链接测试用 Windows 库失败 → program not executable。详见 踩坑2。

3. OHOS_SDK_NATIVE 与编译器同源:都用 C:\DevEcoStudio\sdk\default\openharmony\native。别把编译器指向 DevEco 自带 SDK、OHOS_SDK_NATIVE 指向另一个独立 SDK,混用易出问题。CMAKE_TOOLCHAIN_FILE 只留一条(qt-cmake 本会自己设对,显式给也对)。

可省/可选条目

• CMAKE_TOOLCHAIN_FILE:可整条删(qt-cmake 会自动设);留着须干净(无引号、单条)。
• CMAKE_FIND_ROOT_PATH:不设也能过(ohos.toolchain.cmake 会自设 sysroot)。装了 ohos-additional-packages 再加 -DCMAKE_FIND_ROOT_PATH:PATH=<目录>。
• CMAKE_GENERATOR:若 Kit 已设 Generator=Ninja,可省。

4.3 Generator

Kit 的 CMake Generator 设为 Ninja。

4.4 改完后收尾

• 项目级 Build & Run → CMake 的 Current Configuration 也清空自定义条目(别和 Kit Initial 叠加出重复)。
• 删掉旧 build 目录(CMakeCache.txt 会缓存坏状态/重复条目/无 chainload 状态,不清会复用旧值)。

---

五、构建(configure → 编译 .so)

1. Build → Run CMake(重新 configure)。期望输出:
   • -- The CXX compiler identification is Clang 15.0.4
   • -- Found EGL / -- Found GLESv3
   • -- Configuring done
2. 编译应用目标,产出 lib<target>.so(鸿蒙应用以 .so 形式打包):

   cmake --build . --target <你的目标名>
   

   或直接在 Qt Creator 里点 Build。

configure 报 protoc not found / Qt6GrpcTools NOT FOUND 只是 warning,不影响配置完成(是 QML 经 grpc 的传递依赖,非关键)。

---

六、打 HAP:harmonydeployqt6

configure + 编出 .so 后,用 harmonydeployqt6 把 Qt 产物包成 DevEco/hvigor 工程,再由 hvigor 出 HAP。

6.1 harmonydeployqt6.exe 在哪

在 host 构建 C:\Qt\6.12.0\mingw_64\bin\,不在鸿蒙目标 harmonyos_arm64_v8a\bin\ 里。它是个 Windows host 工具(跟 host 构建走)。同名还有 harmonydeployqt.exe,Qt6 用 harmonydeployqt6.exe。

6.2 方式一:Custom Process Step(手动,对齐 wiki)

Projects → Build & Run → Build Steps → Add Build Step → Custom Process Step:

字段	值
Command	C:\Qt\6.12.0\mingw_64\bin\harmonydeployqt6.exe
Arguments	--input %{buildDir}/<target>-harmony-deployment-settings.json --output %{buildDir}/hap --verbose
Working directory	%{buildDir}

<target> 换成你的目标名(如 samegame → samegame-harmony-deployment-settings.json)。正常打包不加 --no-build、不加 --install(装设备才用);发布加 --release。

6.3 方式二:<target>_make_hap 目标(官方推荐,更省事)

不用配 Custom Process Step。设好第三节的环境变量(尤其 QT_HARMONYOS_HVIGOR),把构建目标设为 <target>_make_hap(Qt CMake 自动生成的目标),等价于:

cmake --build . --target <target>_make_hap

它会自动先编 lib<target>.so 再调 harmonydeployqt 打包,一步到位。官方文档 Building and Deploying Qt Applications for HarmonyOS 推荐此法。

6.4 签名

• 不带任何 --signing-* 参数 → HAP 留未签名 → 用 DevEco Studio 打开 --output 目录(含 entry/、hvigor/、oh-package.json5),在 DevEco 里配签名 + 装设备/模拟器(官方推荐流程)。
• 或命令行签名六件套(须同时给全,密码是 hvigor 加密串):
  --signing-cert-path <.cer> --signing-profile <.p7b> --signing-store-file <.p12> --signing-key-alias <alias> --signing-key-password <密文> --signing-store-password <密文>

---

七、踩坑速查(全实测)

#	症状	根因	修复
1	Could not find toolchain file(文件其实存在)	Kit 初始配置值带首尾 " + :UNINITIALIZED → cmake 收到带字面引号的路径	去引号 + 正确类型(FILEPATH/PATH/STRING)
2	Check for working CXX compiler - broken / program not executable	缺 QT_CHAINLOAD_TOOLCHAIN_FILE → 回退 Linux 默认路径 → OHOS 工具链没加载 → clang 当 host 链 Windows 库	加 QT_CHAINLOAD_TOOLCHAIN_FILE 指向真实 ohos.toolchain.cmake
3	spawn cmd.exe ENOENT(CompileArkTS / es2abc)	传给 es2abc 的进程 PATH 没有 C:\Windows\System32,Node spawn('cmd.exe') 找不到	PATH 带 C:\Windows\System32(或用下面的 .bat wrapper)
4	路径含空格各种随机失败	DevEco 装在 C:\Program Files\...	装无空格路径;或用 8.3 短路径(dir /x 查)
5	同一变量两条(如 :FILEPATH:FILEPATH 笔误)	Kit Initial 与项目 Current Configuration 叠加	两处都清空,只留一条
6	部署报找不到 lib<target>.so	只 configure 没 build	先 cmake --build . --target <target>

踩坑1:Could not find toolchain file(文件其实存在)

症状:configure 报

CMake Error ...: Could not find toolchain file:
"C:/Qt/6.12.0/harmonyos_arm64_v8a/lib/cmake/Qt6/qt.toolchain.cmake"

但你用资源管理器看,这个文件明明存在。

根因:你在 Kit 的 Initial CMake Configuration 里,把值写成了 "C:/.../qt.toolchain.cmake"(带首尾引号)+ 类型用了 :UNINITIALIZED。Qt Creator 把它存成 ""C:/.../qt.toolchain.cmake""(双层引号),cmake 实际收到的路径首尾带字面 " 字符 → if(EXISTS) 判不存在 → 报"找不到"。报错信息里那对引号看着像普通引号,其实是坏值本身。

修复:值不带首尾 ",类型用 FILEPATH/PATH/STRING(不要 :UNINITIALIZED)。即 CMAKE_TOOLCHAIN_FILE:FILEPATH=C:/.../qt.toolchain.cmake(无引号)。

踩坑2:Check for working CXX compiler - broken / program not executable

症状:configure 识别出 Clang 15.0.4,但 Check for working CXX compiler: ... - broken,链接测试报:

clang++: error: unable to execute command: program not executable
clang++: error: linker command failed with exit code 1

根因:QT_CHAINLOAD_TOOLCHAIN_FILE 没设。Qt 的 qt.toolchain.cmake 第 135 行要 chainload 一个 OHOS 工具链,默认值是 Qt 编译时烤进去的 Linux 路径 /opt/harmonyos/command-line-tools/sdk/default/openharmony/native/build/cmake/ohos.toolchain.cmake(在 Windows 上不存在)→ OHOS 工具链(ohos.toolchain.cmake)没加载 → cmake 没设目标三元组/sysroot/OHOS 链接参数 → 把 clang++ 当成普通 Windows host 编译器 → 链接测试用了 Windows 库(-lkernel32 -luser32 …)→ OHOS 交叉 clang++ 链不出 Windows PE → program not executable。

修复:Kit 初始配置里加

-DQT_CHAINLOAD_TOOLCHAIN_FILE:FILEPATH=C:/DevEcoStudio/sdk/default/openharmony/native/build/cmake/ohos.toolchain.cmake

指向真实的 ohos.toolchain.cmake。加完后 OHOS 工具链正常加载,编译器测试即过。

踩坑3:es2abc spawn cmd.exe ENOENT

症状:native 全编过,到 CompileArkTS 步骤失败:

hvigor ERROR: 10310021 ArkTS: INTERNAL ERROR
Failed to initialize or launch the es2abc process. Error: spawn cmd.exe ENOENT

根因:es2abc(ArkTS→ABC 编译器,是个 Node.js 工具,由 hvigor 的 CompileArkTS 任务调)内部要 spawn cmd.exe(启动一个 .cmd 包装),但传给 es2abc 的进程环境 PATH 里没有 C:\Windows\System32(cmd.exe 所在),Node 的 child_process.spawn('cmd.exe') 在 PATH 里搜不到 → spawn cmd.exe ENOENT。

native 阶段不需要 cmd.exe 所以没暴露,到 ArkTS 编译就炸了。常见诱因:在 Kit 的 Environment 里把 PATH 覆盖成了只含 DevEco 几个 bin(把系统 PATH 里的 System32 冲掉了),或 PATH 被设成了 Unix 格式(: 分隔 + /c/...)。

修复(简单):Kit 的 Environment 里,PATH 追加而不是覆盖,且显式带上 System32:

PATH=C:\Windows\System32;C:\Windows;C:\Windows\System32\Wbem;C:\DevEcoStudio\tools\node;C:\DevEcoStudio\jbr\bin;C:\DevEcoStudio\tools\hvigor\bin;C:\DevEcoStudio\tools\ohpm\bin

确保 where cmd.exe 能 resolve 到 C:\Windows\System32\cmd.exe。

修复(更稳,推荐):用下面的 .bat 包一层,强制重置子进程环境,不依赖 QtC 继承到了什么。把 QtC Custom Process Step 的 Command 指向这个 .bat(而非直接调 harmonydeployqt6.exe):

@echo off
REM hap-deploy-qt6.bat -- harmonydeployqt6 wrapper (clean Windows env)
set "ComSpec=C:\Windows\system32\cmd.exe"
set "SystemRoot=C:\Windows"
set "PATH=C:\Windows\System32;C:\Windows;C:\Windows\System32\Wbem;C:\DevEcoStudio\tools\node;C:\DevEcoStudio\jbr\bin;C:\DevEcoStudio\tools\hvigor\bin;C:\DevEcoStudio\tools\ohpm\bin"
set "NODE_HOME=C:\DevEcoStudio\tools\node"
set "JAVA_HOME=C:\DevEcoStudio\jbr\bin"
set "DEVECO_SDK_HOME=C:\DevEcoStudio"
set "QT_HARMONYOS_HVIGOR=C:\DevEcoStudio\tools\hvigor\bin\hvigorw.bat"
"C:\Qt\6.12.0\mingw_64\bin\harmonydeployqt6.exe" %*

QtC Custom Process Step 改成:

• Command:C:\<你放的路径>\hap-deploy-qt6.bat
• Arguments:--input %{buildDir}/<target>-harmony-deployment-settings.json --output %{buildDir}/hap --verbose(去掉 --hvigor,.bat 已设 QT_HARMONYOS_HVIGOR)
• Working directory:%{buildDir}

如果你 DevEco 装在了带空格的 C:\Program Files\Huawei\DevEco Studio,把 .bat 里 DevEco 相关路径换成 8.3 短路径(用 dir /x 查,如 C:\PROGRA~1\Huawei\DEVECO~1\...),或者干脆重装到无空格路径。

踩坑4:带空格路径各种随机失败

DevEco 装在 C:\Program Files\Huawei\DevEco Studio(带空格),PATH/spawn/quote 场景会随机出问题(--hvigor 路径、Node spawn 等)。

修复:优先重装到无空格路径(如 C:\DevEcoStudio)。若不能重装,所有涉及空格路径的环节改用 8.3 短路径(cmd 里 for %I in ("C:\Program Files\Huawei\DevEco Studio") do @echo %~sI 得到 C:\PROGRA~1\Huawei\DEVECO~1)。

---

八、用官方 demo 验证

装 Qt 时勾了 Examples 的话,用官方 demo 验证环境最省事:

1. 打开 C:\Qt\Examples\Qt-6.12.0\demos\xxxx。
2. 按第四节配 Kit → Run CMake → 期望 Configuring done、识别 Clang 15、找到 EGL/GLESv3。
3. cmake --build . --target samegame → 产出 libsamegame.so。
4. 构建 samegame_make_hap 目标(或 harmonydeployqt6 Custom Process Step)→ 产出 --output 目录里的 DevEco 工程(entry/、hvigor/、oh-package.json5)。
5. 用 DevEco Studio 打开该工程 → 配签名 → 装到设备/模拟器跑起来。

能跑通 samegame,环境就算配对了。

---

九、总结

• 安装:Qt 在线安装器勾 HarmonyOS arm64-v8a + MinGW 64-bit(+ CMake/Ninja + Examples);DevEco 装无空格路径。
• Kit 初始配置:粘贴干净的 -D 入参,守三条铁律(去引号+正确类型、QT_CHAINLOAD_TOOLCHAIN_FILE 必填、OHOS_SDK_NATIVE 与编译器同源)。
• 环境变量:NODE_HOME/JAVA_HOME/DEVECO_SDK_HOME/QT_HARMONYOS_HVIGOR,PATH 带 C:\Windows\System32。
• 打 HAP:harmonydeployqt6.exe 在 mingw_64\bin(host 工具);推荐 <target>_make_hap 目标,或 Custom Process Step;未签名 HAP 用 DevEco 签名装机。
• 三大坑:Could not find toolchain file(引号污染)、program not executable(缺 chainload)、spawn cmd.exe ENOENT(PATH 缺 System32)。

照本文走,从安装器到打出 HAP 一次过。祝玩得开心。

---

参考链接

• 官方 wiki:Qt for HarmonyOS development with 6.12.0 Beta2 — Windows
• 官方文档:Building and Deploying Qt Applications for HarmonyOS(<target>_make_hap 目标、harmonydeployqt 工作原理)
• DevEco Studio 下载:https://developer.huawei.com/consumer/cn/deveco-studio/
• Qt 下载:https://www.qt.io/download