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

前言

Qt 经过多年发展，已形成覆盖 桌面工具、工业人机界面、多媒体、科学可视化、专业创作与行业定制 等领域的庞大生态：大量成熟软件以 C++/Qt 交付，采用 qmake（.pro）或 CMake 组织工程，并在 Windows、Linux、macOS 等平台上长期维护。鸿蒙在 平板、2in1 乃至更偏 PC 形态 的设备上持续扩展时，用户与行业对 「可复用的专业软件与开源工具」 的需求与桌面生态并无二致。

在这一背景下，将第三方 Qt 开源软件移植到鸿蒙 PC（及同类设备） 具有几方面重要意义：

1. 保护既有投入，缩短上线周期
   业务逻辑、算法与界面若已在 Qt 中验证，通过交叉编译与壳工程集成即可复用，避免为用新框架从零重写而带来的成本、风险与测试周期膨胀。

2. 快速补齐软件供给
   开源社区与企业内部已有大量 Qt 应用；完成工具链与模板层面的打通后，可以 批量迁移 典型工具类、生产力类与垂直行业应用，丰富鸿蒙侧可用软件目录。

3. 技术路线清晰、可持续演进
   Qt 模块边界清楚，依赖关系可用标准手段（如动态库的 NEEDED）梳理；移植流程一旦标准化，便于团队复现、自动化构建与后续升级 Qt 或 SDK 版本。

4. 促进跨平台协同
   同一套 Qt 源码在桌面与鸿蒙侧并行维护，有利于统一缺陷修复与功能迭代，减少「鸿蒙特供分支」与主线长期分叉带来的合并负担。

因此，掌握 「从 .pro工程 /或者CMake 的工程产出 OHOS 可用的 .so，再接入 DevEco 模板」 的完整路径，不仅是某一两款应用的交付技巧，更是 把全球 Qt 生态能力嫁接到鸿蒙终端 的一块实用基石。下文将从工程形态、构建命令到产物集成逐步展开，供开发与集成人员对照实践。

---

本文面向已在桌面上可正常构建的 Qt5 第三方开源应用，说明如何将其 交叉编译为 OpenHarmony / HarmonyOS 可用的共享库（.so），并借助 DevEco Studio 工程模板（如本仓库 Ohos Template For Qt Application）完成在 平板、2in1（含鸿蒙 PC 形态） 等设备上的加载与运行。

内容覆盖 qmake（.pro）工程 与 CMake 工程 两条常见路径，并给出 Windows 下 CMake 配置示例与产物集成步骤。

---

1. 背景与适用范围

1.1 为何是「.so + ArkUI 壳工程」

在 HarmonyOS / OpenHarmony 上运行传统 Qt Widgets / Qt Quick 应用，通常需要：

1. Qt 官方未提供与手机端相同的「单 HAP 即完整 Qt 应用」标准路径时，社区或厂商会提供 面向 OHOS 的 Qt5 移植（例如基于 Qt for OpenHarmony 等源码树自行编译）。
2. 应用本体被编译为 libYourApp.so（共享库），由模板工程中的 libqohos.so（QPA 平台插件） 在 Ability 生命周期内完成加载、事件与窗口对接。

因此：移植工作的核心是得到与目标 ABI 一致的 .so 及 Qt 依赖库，再拷贝到模板的 entry/libs/<架构>/ 并配置应用库名。

1.2 设备与 ABI 对应关系（务必一致）

典型场景	常用 ABI 目录名
多数鸿蒙平板、ARM 架构 2in1 / PC 形态设备	arm64-v8a
x86 模拟器	x86_64

交叉编译时指定的 OHOS_ARCH（或套件中的架构）必须与打包进 HAP 的 entry/libs/ 子目录一致，否则会出现加载失败或 dlopen 相关错误。

---

2. 环境准备

2.0 环境搭建

关于开发环境搭建，参见博文：
《HarmonyOS鸿蒙PC的QT应用开发：(一、开发环境搭建及第一个HelloWorld)》

《HarmonyOS鸿蒙PC的QT应用开发：(二、开发环境搭建及第一个HelloWorld)》

主要是为 OHOS 编译好的Qt5的SDK（C:/Qt/qt-5.12.12-ohos）。

2.1 必备软件

• HUAWEI DevEco Studio（含 HarmonyOS / OpenHarmony Native SDK、CMake、Ninja 等）
  下载与版本说明见：DevEco Studio
• 已为 OHOS 编译好的 Qt5（下文记为 OHOS_QT_ROOT，例如 C:/Qt/qt-5.12.12-ohos）
  需包含 lib、plugins（或等价布局）及 libqohos.so 所在构建产物（由 Qt-for-OHOS 工程产出，用于模板运行时加载）。
• Qt Creator（可选，用于 .pro 工程切换套件）或 命令行 qmake（与 OHOS Qt 配套）。

2.2 路径约定（文中占位符）

后文命令中的路径请替换为你本机实际安装位置：

占位符	含义	示例（勿照抄，按本机修改）
DEVECO_SDK	DevEco 自带的 OpenHarmony Native SDK 根目录	D:/oh/DevEcoStudio/sdk/HarmonyOS-NEXT-DB6/openharmony/native
OHOS_QT_ROOT	已构建的 Qt for OHOS 安装前缀	C:/Qt/qt-5.12.12-ohos
CMAKE_BIN	SDK 自带的 cmake 可执行文件	.../native/build-tools/cmake/bin/cmake.exe

---

3. 第三方 Qt 工程的两种形态

3.1 使用 Qt Creator 的 qmake 工程（.pro / .pri）

特点： 工程以 .pro 为主，通过套件（Kit）选择交叉编译器与 qmake。

概要步骤：

1. 在 Qt Creator 中配置 OpenHarmony / OHOS 交叉编译套件：
   • 指定 OHOS 工具链中的 C/C++ 编译器；
   • 将 qmake 指向 OHOS_QT_ROOT 下为 OHOS 构建的 qmake（或等价启动方式，以你方 Qt 移植文档为准）。
2. 打开第三方项目的 .pro，切换到上述套件，执行 qmake → 构建。
3. 构建成功后，在生成目录中得到 lib<目标名>.so（具体名称由 TARGET、模板类型等决定，以 .pro 为准）。

在 Qt Creator 中为 HarmonyOS 创建构建套件
(前提，已经构建好了鸿蒙版的Qt的SDK和工具链)

Qt Creator 前往编辑 → 偏好设置 → 构建套件

1、配置 Qt 版本

转到 Qt版本选项卡，单击添加按钮

转到安装 Qt 5.12.12 for OHOS 的文件夹（应安装在 PREFIX 指定的路径中），然后转到 bin 文件夹，选择 qmake 应用程序并单击打开。例如，之前使用 PREFIX=C:\Qt\qt-5.12.12-ohos 编译了 Qt 源代码，因此 qmake 将位于 C:\Qt\qt-5.12.12-ohos\bin\qmake。将名称设置为 Qt %{Qt:Version} for OHOS。此时，应该有信息表明没有可以为此 Qt 版本生成代码的编译器。

接下来，直接使用Qt Creator可以打开工程。

在“配置项目”选项卡中，选择OHOS Clang 套件并单击“配置项目”按钮。

通过单击Build → Build Project “calculator”来触发编译，或者使用快捷键：Ctrl+B。项目应该可以顺利编译。

能够在 qt_creators_projects\build-calculator-OHOS_Clang-Debug 文件夹中 找到已编译的libcalculator.so文件。

注意：

• 若原工程写死了 win32/linux 平台判断，需增加对 ohos 或对应 mkspec 的分支（例如链接库、插件路径、DEFINES）。
• 输出必须是 共享库 且导出符号满足 QPA/启动约定时，才能被模板按「应用库」加载；若为可执行文件，需按 Qt-for-OHOS 文档改为库形态或增加启动封装（超出本文默认模板流程）。

关键步骤总结:

1. 在Qt Creator中配置OpenHarmony交叉编译套件
2. 指定OHOS工具链中的C/C++编译器
3. 将qmake指向OHOS_QT_ROOT下的qmake
4. 打开第三方项目的.pro，切换到配置好的套件
5. 执行qmake → 构建，得到lib<目标名>.so
   注意事项:
   • 若原工程写死了平台判断，需增加对ohos的分支处理
   • 输出必须是共享库且导出符号满足QPA/启动约定

3.2 CMake 工程（推荐脚本化、可复用）

特点： 通过 CMAKE_TOOLCHAIN_FILE 使用 OHOS 官方工具链，并指定 Qt5 的 CMAKE_PREFIX_PATH / Qt5_DIR。

3.2.1 Windows 命令行示例

在 源码旁 创建并进入构建目录（示例为 build）：

cd /d E:\test\qt\notepad---main\build

配置（Configure）：

"%DEVECO_SDK%\build-tools\cmake\bin\cmake.exe" 
  -G "Ninja" 
  -DCMAKE_PREFIX_PATH="C:/Qt/qt-5.12.12-ohos" 
  -DCMAKE_TOOLCHAIN_FILE="D:/oh/DevEcoStudio/sdk/HarmonyOS-NEXT-DB6/openharmony/native/build/cmake/ohos.toolchain.cmake" 
  -DQt5_DIR="C:/Qt/qt-5.12.12-ohos/lib/cmake/Qt5" 
  -DCMAKE_FIND_ROOT_PATH="C:/Qt/qt-5.12.12-ohos" 
  -DOHOS_ARCH=arm64-v8a 
  ..

说明：

• -G "Ninja"：与 SDK 自带构建工具配合使用；若你使用其他生成器，需保证工具链一致。
• -DCMAKE_TOOLCHAIN_FILE：必须 指向当前 SDK 版本下的 ohos.toolchain.cmake。
• -DOHOS_ARCH：与上一节 ABI 一致；模拟器可改为 x86_64（以工具链支持为准）。
• -DCMAKE_PREFIX_PATH / -DCMAKE_FIND_ROOT_PATH / -DQt5_DIR：让 CMake 在 OHOS Qt 前缀内 查找 Qt5 模块，避免误用 Windows 桌面版 Qt。

构建（Build）：

"%DEVECO_SDK%\build-tools\cmake\bin\cmake.exe" --build .

配置与构建成功后，在构建树中查找生成的 lib*.so（名称取决于 add_library / BUILD_SHARED_LIBS 等）。

3.2.2 常见 CMake 调整

• 第三方库若默认构建静态库，需改为 SHARED 或与模板约定一致。
• 使用 find_package(Qt5 COMPONENTS Widgets Network ...) 时，确保组件在 OHOS Qt 中已构建。
• 若出现找不到头文件/库，检查 CMAKE_FIND_ROOT_PATH_MODE 是否被项目覆盖，以及是否错误地 link_directories 到主机路径。

3.2.3 附bat构建脚本(build_ohos.bat)

直接在命令行窗口敲cmake命令太繁琐，下面直接给出windows下的批处理脚本。

@echo off
setlocal

:: ==========================================
:: 作者：猫哥
:: 邮箱：[534117529@qq.com]
:: 博客：[blog.csdn.net/qq8864]
:: 描述：QT的Cmake工程的鸿蒙PC平台编译脚本
:: ==========================================

:: ==========================================
:: 配置项自定义区
:: ==========================================

:: SDK 与 工具链路径
set SDK_PATH=D:\oh\DevEcoStudio\sdk\HarmonyOS-NEXT-DB6\openharmony\native
set CMAKE_EXE=%SDK_PATH%\build-tools\cmake\bin\cmake.exe
set TOOLCHAIN=%SDK_PATH%\build\cmake\ohos.toolchain.cmake

:: Qt 相关路径
set QT_ROOT=C:/Qt/qt-5.12.12-ohos
set QT_DIR=%QT_ROOT%/lib/cmake/Qt5

:: 编译配置
set ARCH=arm64-v8a
set BUILD_TYPE=Debug
set SOURCE_DIR=../

:: ==========================================
:: 第一步：配置项目 (CMake Configure)
:: ==========================================

echo [信息] 正在启动面向 OpenHarmony 的 CMake 配置...
echo [信息] 目标架构: %ARCH%

"%CMAKE_EXE%" ^
    -G "Ninja" ^
    -DCMAKE_BUILD_TYPE=%BUILD_TYPE% ^
    -DOHOS_ARCH=%ARCH% ^
    -DCMAKE_TOOLCHAIN_FILE="%TOOLCHAIN%" ^
    -DCMAKE_PREFIX_PATH="%QT_ROOT%" ^
    -DQt5_DIR="%QT_DIR%" ^
    -DCMAKE_FIND_ROOT_PATH="%QT_ROOT%" ^
    %SOURCE_DIR%

if %ERRORLEVEL% NEQ 0 (
    echo [错误] CMake 配置阶段失败!
    pause
    exit /b %ERRORLEVEL%
)

:: ==========================================
:: 第二步：执行构建 (CMake Build)
:: ==========================================

echo [信息] 配置成功，正在开始构建项目...

:: 使用 --build 参数跨平台调用 Ninja 编译
"%CMAKE_EXE%" --build .

if %ERRORLEVEL% NEQ 0 (
    echo [错误] 编译构建阶段失败!
    pause
    exit /b %ERRORLEVEL%
)

echo [成功] 恭喜，编译顺利完成！
pause

---

4. 得到 .so 之后：与本仓库 DevEco 模板对接

以下步骤与 本仓库「Ohos Template For Qt Application」 类工程一致。

可以在以下地址获取最新的用于构建最终 OpenHarmony Qt 应用程序的 DevEco 项目模板。这将用于在 HarmonyOS 设备上运行 Qt 应用程序。

获取最新模版: http://codereview.qtcompany.cn:29416/template/

将 DevEco 项目模板放入已知位置。我们将其命名为
转到文件夹 \entry 并创建一个文件夹 \ entry\libs\arm64-v8a

4.1 拷贝共享库到 entry/libs/<ABI>/

将下列文件放入对应 ABI 目录（二者架构必须一致）：

1. 你的应用库，例如 libnotepad.so（名称以实际产物为准）。
2. libqohos.so：OHOS QPA 插件，来自 Qt-for-OHOS 构建产物（模板中通过 import qpa from 'libqohos.so' 加载）。
3. Qt 运行依赖库，例如常见依赖：
   libQt5Core.so、libQt5Gui.so、libQt5Widgets.so 等（具体列表以你应用链接为准）。

查找依赖的技巧： 在 Linux 或 WSL 下对 .so 使用 readelf -d libYourApp.so | grep NEEDED，或在 OHOS 文档推荐工具中查看，避免漏拷导致运行时 dlopen 失败。

目录示例：

entry/libs/arm64-v8a/
  libYourApp.so
  libqohos.so
  libQt5Core.so
  libQt5Gui.so
  libQt5Widgets.so
  ... 其他 NEEDED 库 ...

一旦复制了所有库，我们就可以修改 ets源代码。打开文件 <deveco-project>\entry\src\main\ets\common\QtAppConstants.ets。将 APP_LIBRARY_NAME 变量更改为我们要使用的库的名称（libcalculator.so）：

3. 构建并运行应用程序

确保设备已连接。连接后，它应该在 DevEco Studio 中可见。

然后添加签名配置，打开 file–project structure–signing configs，勾选所有项，点击OK。(测试期间可以使用自动签名)

4.2 配置应用库文件名

在本仓库中，应用库名在 entry/src/main/ets/common/QtAppConstants.ets 的常量 APP_LIBRARY_NAME 中设置，例如：

export const APP_LIBRARY_NAME = 'libYourApp.so';

该名称会传入 qpa.setupQtApplication({ appName: APP_LIBRARY_NAME, ... })（见 QAbilityStage.ets），须与实际文件名一致（含 lib 前缀与 .so 后缀的写法以模板与 QPA 约定为准，当前模板使用完整库名字符串）。

4.3 Ability / 设备类型与权限

• 模板 entry/src/main/module.json5 中声明了 tablet、2in1 等设备类型，与 鸿蒙 PC / 2in1 场景一致；若需扩展其他类型，请按产品要求修改并评估窗口行为。
• 若应用使用网络、剪贴板、相机等，需保留或增补 requestPermissions 中与业务匹配的权限声明。

4.4 签名与运行

在 DevEco Studio 中配置 签名（build-profile.json5 中 signingConfigs），连接设备或启动模拟器，编译安装 HAP，即可验证 Qt 界面是否由 QPA 正确拉起。

---

5. 调试与排错建议

现象	可能原因	处理方向
启动即崩溃 / 日志提示找不到库	entry/libs 未放全、NEEDED 遗漏	补全依赖 .so，核对 ABI 子目录
仅 x86_64 模拟器可跑，真机不行	使用了错误架构产物	用 OHOS_ARCH=arm64-v8a 重编并放入 arm64-v8a
libqohos.so 相关错误	未拷贝或与 Qt 版本不匹配	使用与 当前 OHOS Qt 同源构建的 libqohos.so
CMake 找到桌面 Qt	CMAKE_PREFIX_PATH 未指向 OHOS Qt	清理缓存，强制指定 Qt5_DIR 与 FIND_ROOT_PATH

---

6. 小结

• .pro 工程：在 Qt Creator 中切换到 OHOS Qt 套件，构建得到 lib*.so。
• CMake 工程：在 Windows 下用 SDK 自带 cmake + Ninja，指定 ohos.toolchain.cmake、OHOS_ARCH 与 OHOS Qt 的 CMAKE_PREFIX_PATH / Qt5_DIR，再 cmake --build。
• 集成阶段：将 应用 .so + libqohos.so + Qt 依赖** 放入 **entry/libs//**，并在模板中设置 **APP_LIBRARY_NAME`（本仓库），即可按与 本工程 相同方式打包运行。

---

7. 参考链接

• HUAWEI DevEco Studio
• Qt for OpenHarmony（示例源码托管）
• https://wiki.qt.io/Qt_for_OpenHarmony/zh

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