好消息！2026年3.31日，QT官方正式发布鸿蒙版QT。本次开源发布正式推出面向鸿蒙系统平板和PC设备的Qt 5.12.12 LTS 适配版本，在完整保留 Qt 5.12.12 核心能力（含界面渲染、信号槽机制、跨平台 I/O、网络通信及数据库模块）的基础上，深度适配鸿蒙系统架构。本版本可降低开发者跨平台移植成本，加速 Qt 与鸿蒙生态融合，助力多场景鸿蒙应用高效开发。

QT官方鸿蒙版开源地址：https://wiki.qt.io/Qt5.12.12_Open_Source_Release_for_HarmonyOS_zh

QT官方文档地址：https://wiki.qt.io/Qt_for_OpenHarmony/zh

在 HarmonyOS 上运行 Qt 应用，跟传统的PC上的QT应用不同。

传统的PC上的QT应用是使用QtCreator开发完成后，直接编译为可执行文件exe.。 而鸿蒙版QT的开发流程，则是使用鸿蒙版QT的SDK和qmake工具链，最终的编译产物为.so. 之后呢还需要鸿蒙的QT工程项目模版，把so加载进去，将应用编译打包为hap或app包。

本文介绍下鸿蒙版QT的开发环境搭建（本文以Windows环境为例）及第一个HelloWorld。

这个环境搭建看似繁琐，是因为QT官方只丢出来了源码，没有给出编译好的QT的so库。这里只需把源码编译一次即可，后面博主给出编译好的QT库链接就没有那么麻烦了。

一、环境准备

1. 华为 DevEco Studio 安装

如果您想开发Qt for HarmonyOS应用程序，除了使用Qt Creator之外，还需要依赖DevEco Studio。

https://developer.huawei.com/consumer/cn/deveco-studio/

一般情况下，不需要配置DevEco Studio使用的sdk版本，因为DevEco Studio默认自带了一个sdk。

2. Qt Creator安装

下载安装QT5.12.12版本或5.12.12之上的其他版本如5.14或5.15也可以，其中包含了QTCreator开发环境IDE。

3. 获取 Qt for HarmonyOS 源代码

源码下载地址：https://wiki.qt.io/Qt5.12.12_Open_Source_Release_for_HarmonyOS_zh

4. 下载 MinGW 工具链
为了在windows上编译鸿蒙的QT工具链，需要下载安装MinGW 。

下载地址：https://github.com/mstorsjo/llvm-mingw/releases

5. 安装Perl环境
下载地址：https://strawberryperl.com/

二、在 Windows 中为 HarmonyOS 构建 Qt 库

为了方便统一，建议在D盘创建oh目录，将源码解压到D:\oh\tqtc-qt5目录下。

注意： 如果你的devstudio安装到了其他盘如 D:\Program Files\Huawei\DevEco Studio,

需要注意：因为使用路径时不能有空格，可以新建一个D:\oh\DevEcoStudio目录，将工具链路径：D:\Program Files\Huawei\DevEco Studio\sdk\default\openharmony\native中的内容，放在D:\oh\DevEcoStudio\sdk\HarmonyOS-NEXT-DB6\openharmony\native目录下。

1.将上一步环境准备中的MinGW 和Perl路径添加到 PATH 环境变量中。

如下所示：

2.另外在系统环境变量中添加 MINGW_ROOT 和 PERL_ROOT ：

3.打开命令提示符 （使用CMD工具，注。必须使用cmd命令行窗口，powershell不行） ，并按照一下方式设置环境变量：

#REM set NATIVE_OHOS_SDK 
SET NATIVE_OHOS_SDK=D:\oh\DevEcoStudio\sdk\HarmonyOS-NEXT-DB6\openharmony\native

#REM set OHOS_SDK_SYSROOT 
SET OHOS_SDK_SYSROOT=%NATIVE_OHOS_SDK%\sysroot

#REM set LLVM_INSTALL_DIR 
SET LLVM_INSTALL_DIR=%NATIVE_OHOS_SDK%\llvm

#REM set Qt source directory
SET QT5_ROOT_DIR=D:\oh\tqtc-qt5

4.开始构建鸿蒙版QT库

使用相同的命令提示符找到你的 qt5 仓库目录并创建与之并行的build目录（不要设置build目录是 qt5 仓库目录的子目录）。然后转到 build 目录，设置一个包含跳过的部分子模块的变量并运行 configure命令：

#REM set QT_SKIPS 
SET QT_SKIPS=-skip qt3d -skip qtactiveqt -skip qtandroidextras -skip qtcanvas3d -skip qtconnectivity -skip qtdatavis3d -skip qtdoc -skip qtdocgallery -skip qtfeedback -skip qtgamepad -skip qtgraphicaleffects -skip qtlocation -skip qtmacextras -skip qtnetworkauth -skip qtpim -skip qtpurchasing -skip qtqa -skip qtremoteobjects -skip qtrepotools -skip qtscript -skip qtscxml -skip qtsensors -skip qtserialbus -skip qtserialport -skip qtspeech -skip qtsystems -skip qttools -skip qttranslations -skip qtvirtualkeyboard -skip qtwayland -skip qtwebchannel -skip qtwebengine -skip qtwebglplugin -skip qtwebsockets -skip qtwebview -skip qtwinextras -skip qtx11extras -no-dbus -skip doc

# 先进入build目录下
cd build
#REM  configure command
call ..\tqtc-qt5\configure.bat -v -xplatform ohos-clang -device-option CROSS_COMPILE=%LLVM_INSTALL_DIR%\bin -prefix /data/storage/el1/bundle/libs/arm64 -extprefix c:\Qt\qt-5.12.12-ohos -opensource -confirm-license -debug -no-use-gold-linker %QT_SKIPS% -nomake tests -nomake examples -no-gcc-sysroot -opengles3 -c++std c++14 -ohos-arch arm64-v8a

上面的-extprefix c:\Qt\qt-5.12.12-ohos 选项指定了最终生成库的路径位置，可根据实际需要更改。

注意：如果你需要openssl的相关特性，请执行configure命令的时候添加以下选项： -openssl-runtime -I%QT_SOURCE_DIR_OPENSSL% -ssl

-openssl-runtime -I%QT_SOURCE_DIR_OPENSSL% -ssl

其中变量%QT_SOURCE_DIR_OPENSSL%代表openssl头文件的路径, openssl的头文件可以从这个地址获得：https://gitcode.com/openharmony/third_party_openssl/tree/master/include/openssl

5.配置成功后，您可以使用 mingw32-make进行构建：

 mingw32-make -j8

6.构建成功后，您可以使用以下命令开始安装：

 mingw32-make install

经过上面步骤，最终我编译成功的库在以下路径：

注：因为上面的call ..\tqtc-qt5\configure.bat ... -extprefix c:\Qt\qt-5.12.12-ohos 选项指定了最终生成库的路径位置，可根据实际需要更改。

三、编译报错及解决（FAQ）

error: enumeration valuesIMAGE UNSUPPORTED DATA FORMAT’IMAGE CREATE PIXELMAP FAILEDin switch [-Werror,-Wswitch

这个原因是把编译警告当成了错误，解决办法：
修改makefile文件，
D:\oh\build\qtmultimedia\src\plugins\ohos\src，

修改后： CXXFLAGS = … -Werror -Wall -Wno-switch

最后，欢迎加入开源鸿蒙开发者社区交流：https://harmonypc.csdn.net/

附录：延伸阅读

以下链接供查阅嵌入式 UI 扩展与 HarmonyOS Ability 相关内容：

1. HarmonyOS 嵌入式 UI 扩展组件实战 - 博客园

2. HarmonyOS 应用开发中 EmbeddedUIExtensionAbility：跨进程 UI 嵌入 - SegmentFault

3. 知乎专栏

4. https://wiki.qt.io/Qt_for_OpenHarmony/zh?login=from_csdn

5. https://wiki.qt.io/Qt5.12.12_Open_Source_Release_for_HarmonyOS_zh

官方文档请优先参考：HarmonyOS 开发者官网。