Qt 开源软件适配鸿蒙 PC 小白复现步骤（实战指南记录）

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

本文面向第一次做 Qt / C++ 开源软件鸿蒙 PC 适配的同学。目标不是一上来就硬啃 KDiff3，而是按三个阶段复现：

这样做的好处是：先证明环境没问题，再证明三方库能编，再去改真实开源项目。哪里失败，就能知道问题大概在哪一层。
在这里插入图片描述

0. 先理解整体流程

Qt 软件适配到鸿蒙 PC，大体不是“把 exe 拷过去运行”，而是下面这条链路：

Qt/C++ 源码
  ↓
使用 HarmonyOS / OpenHarmony SDK 交叉编译
  ↓
生成 arm64-v8a 的 .so 动态库
  ↓
放进 DevEco Stage/HAP 工程
  ↓
HAP 安装到鸿蒙 PC
  ↓
鸿蒙应用启动后加载 Qt runtime 和你的业务 .so

你要记住几个关键词：

名词 小白理解
OpenCloudOS / Ubuntu / WSL 构建主机，用来敲命令、编译源码
鸿蒙 PC 目标运行设备
DevEco Studio 打 HAP 包、安装运行的 IDE
OHOS SDK 鸿蒙交叉编译工具链
Qt for HarmonyOS 能在鸿蒙上运行的 Qt 版本
vcpkg-ohos 给鸿蒙编译 C/C++ 三方库的包管理工具
arm64-ohos vcpkg 里的鸿蒙 arm64 目标
arm64-v8a HAP 工程里的鸿蒙 arm64 ABI 目录
binary-sign-tool 给 .so / ELF 签名的工具

1. 准备机器

你需要两类环境。

1.1 构建主机

任选一个：

方案 A：Windows + WSL Ubuntu 22.04/24.04
方案 B：OpenCloudOS x86_64
方案 C：普通 Linux 服务器 x86_64

小白推荐：

Windows + WSL Ubuntu

如果你现在已经有 OpenCloudOS，也可以用。注意 OpenCloudOS 建议是 x86_64，因为常见 OHOS SDK Linux 工具链是 Linux x64 主机工具。

检查架构：

uname -m

推荐看到：

x86_64

1.2 鸿蒙 PC / 测试设备

用来安装和运行 HAP。你需要：

鸿蒙 PC 真机
开发者模式
hdc 可用
DevEco Studio 可连接设备

2. 构建主机安装基础工具

2.1 Ubuntu / WSL

sudo apt update
sudo apt install -y \
  git cmake ninja-build \
  python3 python3-pip \
  unzip zip tar gzip xz-utils \
  pkg-config \
  build-essential \
  curl wget patch perl file

检查：

git --version
cmake --version
ninja --version
python3 --version

2.2 OpenCloudOS

sudo dnf makecache
sudo dnf install -y \
  git cmake ninja-build \
  python3 python3-pip \
  unzip zip tar gzip xz \
  pkgconf-pkg-config \
  gcc gcc-c++ make \
  curl wget patch perl file which

在这里插入图片描述
如果没有 dnf，用 yum：

sudo yum makecache
sudo yum install -y \
  git cmake ninja-build \
  python3 python3-pip \
  unzip zip tar gzip xz \
  pkgconf-pkg-config \
  gcc gcc-c++ make \
  curl wget patch perl file which

检查：

cmake --version
ninja --version

建议 CMake 版本：

3.22 或以上

如果版本太旧，后面 KDiff3 可能配置失败。
在这里插入图片描述

3. 准备 HarmonyOS / OpenHarmony SDK

下载地址：

http://dcp.openharmony.cn/workbench/cicd/dailybuild/dailylist

交叉编译选 ohos-sdk-full；原生编译选 ohos-sdk-public_ohos。
阶段1：下载 SDK

# 使用国内镜像下载（推荐）
wget "https://cidownload.openharmony.cn/version/Daily_Version/OpenHarmony_7.0.0.26/20260522_000324/version-Daily_Version-OpenHarmony_7.0.0.26-20260522_000324-ohos-sdk-full.tar.gz"

在这里插入图片描述
阶段2：解压主包

# 创建目录并解压
mkdir -p /root/ohos-sdk
tar -xzf version-Daily_Version-OpenHarmony_7.0.0.26-20260522_000324-ohos-sdk-full.tar.gz -C /root/ohos-sdk/

阶段3：解压工具链组件

# 进入 linux 目录
cd /root/ohos-sdk/ohos-sdk/linux/

# 解压 native 工具链（包含交叉编译器）
unzip native-linux-x64-26.0.0.26-Beta.zip

# 解压 toolchains（包含签名工具等）
unzip toolchains-linux-x64-26.0.0.26-Beta.zip

阶段4：设置环境变量

# 临时设置（当前会话有效）
export OHOS_SDK_ROOT=/root/ohos-sdk/ohos-sdk/linux
export PATH=$OHOS_SDK_ROOT/native/llvm/bin:$PATH

# 永久设置（写入 ~/.bashrc）
cat >> ~/.bashrc <<'EOF'
export OHOS_SDK_ROOT=/root/ohos-sdk/ohos-sdk/linux
export PATH=$OHOS_SDK_ROOT/native/llvm/bin:$PATH
EOF

# 生效环境变量
source ~/.bashrc

阶段5：验证配置

# 检查工具链文件
ls $OHOS_SDK_ROOT/native/build/cmake/ohos.toolchain.cmake

# 检查 clang 编译器
ls $OHOS_SDK_ROOT/native/llvm/bin/clang

# 检查签名工具
ls $OHOS_SDK_ROOT/toolchains/lib/binary-sign-tool

# 验证 clang 版本
clang --version

在这里插入图片描述
📁 最终目录结构

/root/ohos-sdk/
└── ohos-sdk/
    └── linux/
        ├── native/
        │   ├── build/cmake/ohos.toolchain.cmake
        │   └── llvm/bin/clang
        └── toolchains/
            └── lib/binary-sign-tool

现在你已经完成了 OHOS SDK 的配置，可以开始进行 Qt 应用的鸿蒙 PC 适配开发了！🎉

4. 准备 Qt for HarmonyOS

1. 创建目录并克隆仓库

mkdir -p /opt/qt-ohos
cd /opt/qt-ohos
git clone https://gitcode.com/OpenHarmonyPCDeveloper/ohos_Qt5.12.12.git .

2. 使用 Git LFS 下载二进制包

# 确保已安装 git-lfs
git lfs pull

3. 解压 Qt 包

mkdir -p /opt/qt-ohos/qt-5.12.12-ohos
unzip /opt/qt-ohos/qt_ohos_release/qt-5.12.12-ohos_release_20260420.zip -d /opt/qt-ohos/qt-5.12.12-ohos

4. 设置环境变量

# 临时设置
export QT_OHOS_ROOT=/opt/qt-ohos/qt-5.12.12-ohos

# 永久设置
cat >> ~/.bashrc <<'EOF'
export QT_OHOS_ROOT=/opt/qt-ohos/qt-5.12.12-ohos
EOF

source ~/.bashrc

5. 验证 Qt

find $QT_OHOS_ROOT -name "Qt5Config.cmake"
# 期望输出：/opt/qt-ohos/qt-5.12.12-ohos/lib/cmake/Qt5/Qt5Config.cmake

在这里插入图片描述

✅ OHOS SDK 工具链文件存在
✅ clang 编译器可执行
✅ 签名工具存在
✅ Qt5Config.cmake 存在
✅ 环境变量已正确设置

🎉 配置完成！ 现在你已经具备了 Qt 应用鸿蒙 PC 移植的完整开发环境。

5. 第一阶段：复现最小 Qt Widgets Demo

验证 Qt + OHOS SDK 交叉编译环境是否正常工作

1. 创建项目目录

mkdir -p ~/qt-ohos-demo
cd ~/qt-ohos-demo

2. 创建 main.cpp

#include <QApplication>
#include <QLabel>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    QLabel label("Hello Qt on HarmonyOS PC");
    label.resize(480, 120);
    label.show();
    return app.exec();
}

3. 创建 CMakeLists.txt

cmake_minimum_required(VERSION 3.22)
project(qt_ohos_demo)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE BOTH)  # OHOS交叉编译关键配置

find_package(Qt6 COMPONENTS Core Gui Widgets QUIET)
if(Qt6_FOUND)
    set(QT_PACKAGE Qt6)
else()
    find_package(Qt5 REQUIRED COMPONENTS Core Gui Widgets)
    set(QT_PACKAGE Qt5)
endif()

add_library(qt_ohos_demo SHARED main.cpp)
target_link_libraries(qt_ohos_demo PRIVATE
    ${QT_PACKAGE}::Core ${QT_PACKAGE}::Gui ${QT_PACKAGE}::Widgets)

4. 配置构建

cmake -S . -B build-ohos -GNinja \
  -DCMAKE_TOOLCHAIN_FILE=$OHOS_SDK_ROOT/native/build/cmake/ohos.toolchain.cmake \
  -DCMAKE_PREFIX_PATH=$QT_OHOS_ROOT

5. 编译

ninja -C build-ohos

在这里插入图片描述

关键配置

# 环境变量
export OHOS_SDK_ROOT=/root/ohos-sdk/ohos-sdk/linux
export QT_OHOS_ROOT=/opt/qt-ohos/qt-5.12.12-ohos/qt-5.12.12-ohos
export PATH=$OHOS_SDK_ROOT/native/llvm/bin:$PATH

问题与解决

问题 原因 解决方法
CMake找不到Qt5 QT_OHOS_ROOT路径错误 修正为嵌套路径 /opt/qt-ohos/qt-5.12.12-ohos/qt-5.12.12-ohos

✅ 交叉编译环境配置成功！

  • OHOS SDK 工具链正常工作
  • Qt for HarmonyOS 配置正确
  • 成功生成 ARM64 架构的 Qt 动态库

在这里插入图片描述

在这里插入图片描述

6. 第二阶段：准备 DevEco HAP 壳工程

这一步在 DevEco Studio 里做。

6.1 创建工程

在 DevEco Studio 中：

File
  New
    Create Project

选择一个最简单的 Stage 模板。工程名可以叫：

QtOhosDemo

目标结构大致类似：

QtOhosDemo/
  entry/
    src/main/
      ets/
      cpp/
    libs/

如果你使用的是 Qt for HarmonyOS 官方模板，里面通常已经有加载 Qt runtime 的代码。

6.2 设置加载库名

找到类似文件：

entry/src/main/ets/common/QtAppConstants.ets

设置：

export const APP_LIBRARY_NAME = 'libqt_ohos_demo.so';

如果你的模板没有这个文件，就搜索：

APP_LIBRARY_NAME
loadLibrary
libqohos

目标是让 HAP 启动时加载：

libqt_ohos_demo.so

6.3 放入动态库

创建目录：

entry/libs/arm64-v8a/

把下面文件放进去：

libqt_ohos_demo.so
libqohos.so
libQt6Core.so 或 libQt5Core.so
libQt6Gui.so 或 libQt5Gui.so
libQt6Widgets.so 或 libQt5Widgets.so

libqt_ohos_demo.so 来自：

~/qt-ohos-demo/build-ohos/libqt_ohos_demo.so

Qt runtime 的 .so 来自你的 Qt for HarmonyOS 安装目录。

6.4 签名 .so

在构建主机上签名：

export SIGN_TOOL=$OHOS_SDK_ROOT/toolchains/lib/binary-sign-tool

cd /path/to/QtOhosDemo/entry/libs/arm64-v8a

$SIGN_TOOL sign -inFile libqt_ohos_demo.so -outFile libqt_ohos_demo.so -selfSign 1

如果你自己拷贝了其他三方库 .so，也一起签名。

6.5 运行

在 DevEco Studio 中：

Sync Project
Build Hap
Run

成功标志：

鸿蒙 PC 上出现一个窗口，显示 Hello Qt on HarmonyOS PC

在这里插入图片描述

如果这里成功，说明：

Qt runtime 可以加载
HAP 壳工程可以运行
你的业务 .so 可以被鸿蒙应用加载

7. 第三阶段：复现 vcpkg-ohos

这一步证明三方 C/C++ 库能为鸿蒙编译。

7.1 获取 vcpkg-tool

cd ~
git clone https://git.qt.io/jobor/vcpkg-tool.git -b ohos ~/vcpkg-tool
cd ~/vcpkg-tool
cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
ninja -C build

成功标志：

ls ~/vcpkg-tool/build/vcpkg

如果 Qt 官方源下载慢，可以换镜像：

git clone https://gitcode.com/qq8864/vcpkg-tool.git -b ohos ~/vcpkg-tool

7.2 获取 vcpkg registry

cd ~
git clone https://git.qt.io/jobor/vcpkg.git -b ohos ~/vcpkg
cd ~/vcpkg
cp ~/vcpkg-tool/build/vcpkg ./
export VCPKG_ROOT=~/vcpkg

镜像方式：

git clone https://gitcode.com/qq8864/vcpkg.git -b ohos ~/vcpkg

建议写入 ~/.bashrc：

cat >> ~/.bashrc <<'EOF'
export VCPKG_ROOT=$HOME/vcpkg
EOF
source ~/.bashrc

7.3 安装一个最小库

先安装 zlib：

cd $VCPKG_ROOT
./vcpkg install zlib:arm64-ohos

成功标志：

ls $VCPKG_ROOT/installed/arm64-ohos/lib

检查 ABI：

$OHOS_SDK_ROOT/native/llvm/bin/llvm-readelf -h \
  $VCPKG_ROOT/installed/arm64-ohos/lib/libz.so

应看到：

Machine: AArch64

7.4 再安装 KDiff3 可能用到的库

KDiff3 第一版常见外部依赖：

cd $VCPKG_ROOT
./vcpkg install boost:arm64-ohos icu:arm64-ohos

成功标志：

$VCPKG_ROOT/installed/arm64-ohos/include
$VCPKG_ROOT/installed/arm64-ohos/lib

如果失败，先看错误里是不是：

Could not find OHOS SDK

这种情况通常是：

export OHOS_SDK_ROOT=/root/ohos-sdk/linux

没设置或路径错了。

8. 第四阶段：开始复现 KDiff3 适配

前面三个阶段都成功后，再进入 KDiff3。

8.1 拉源码

mkdir -p ~/ohos-qt-port
cd ~/ohos-qt-port

git clone https://invent.kde.org/sdk/kdiff3.git
cd kdiff3
git checkout 1.12
git checkout -b ohos-port

GitHub 镜像：

git clone https://github.com/KDE/kdiff3.git

8.2 先在 Linux 编译原版

cmake -S . -B build-linux -GNinja -DCMAKE_BUILD_TYPE=Release
ninja -C build-linux

这一步的意义是确认源码本身能构建。失败就先补 Linux 依赖。

8.3 确认 KDiff3 的难点

KDiff3 不是纯 Qt 项目，它还依赖 KDE Frameworks：

KIO
KConfig
KXmlGui
KCrash
KI18n
KCoreAddons

小白第一版不要全量移植 KDE Frameworks。先做：

本地文件版 KDiff3

第一版策略：

原功能 第一版处理
KIO 网络文件 先禁用
KXmlGuiWindow 改 QMainWindow
KConfig 改 QSettings
KI18n 改 tr()
KCrash 先屏蔽
diff/merge 核心逻辑 保留

8.4 修改 CMake 生成 .so

打开：

src/CMakeLists.txt

找到：

add_executable(kdiff3 ${kdiff3_SRCS})

改成：

option(KDIFF3_BUILD_OHOS "Build KDiff3 for HarmonyOS" OFF)

if(KDIFF3_BUILD_OHOS)
    add_library(kdiff3 SHARED ${kdiff3_SRCS})
else()
    add_executable(kdiff3 ${kdiff3_SRCS})
endif()

增加宏：

if(KDIFF3_BUILD_OHOS)
    target_compile_definitions(kdiff3 PRIVATE
        KDIFF3_OHOS=1
        HAS_KFKIO=0
    )
endif()

8.5 屏蔽 KIO

遇到：

#include <KIO/CopyJob>
#include <KIO/ListJob>
#include <KIO/StatJob>

先改成：

#ifndef KDIFF3_OHOS
#include <KIO/CopyJob>
#include <KIO/ListJob>
#include <KIO/StatJob>
#endif

本地文件操作用 Qt：

QFile
QDir
QFileInfo
QDirIterator
QSaveFile

8.6 替换 KXmlGuiWindow

遇到：

#include <KXmlGuiWindow>
class KDiff3Shell : public KXmlGuiWindow

改成：

#include <QMainWindow>
class KDiff3Shell : public QMainWindow

菜单先用 Qt 原生菜单：

auto *fileMenu = menuBar()->addMenu(tr("&File"));
auto *openAction = fileMenu->addAction(tr("&Open"));

8.7 替换 KConfig

遇到：

#include <KConfig>
#include <KConfigGroup>

第一版改：

#include <QSettings>

保存设置示例：

QSettings settings("OpenHarmonyPCDeveloper", "KDiff3");
settings.setValue("window/geometry", saveGeometry());

读取设置示例：

QSettings settings("OpenHarmonyPCDeveloper", "KDiff3");
restoreGeometry(settings.value("window/geometry").toByteArray());

8.8 替换 KI18n

遇到：

i18n("Open")

先改成：

tr("Open")

非 QObject 成员函数里可以先用：

QObject::tr("Open")

8.9 屏蔽 KCrash

遇到：

KCrash::initialize();

改成：

#ifndef KDIFF3_OHOS
KCrash::initialize();
#endif

9. KDiff3 接入 DevEco HAP 工程

如果最小 Demo 已经跑通，就复用那个 HAP 壳。

把库名改成：

export const APP_LIBRARY_NAME = 'libkdiff3.so';

把构建出的：

libkdiff3.so

放到：

entry/libs/arm64-v8a/

同时放入 Qt runtime 和 KDiff3 依赖的三方库，例如：

libqohos.so
libQt6Core.so 或 libQt5Core.so
libQt6Gui.so 或 libQt5Gui.so
libQt6Widgets.so 或 libQt5Widgets.so
libQt6PrintSupport.so 或 libQt5PrintSupport.so
libicuuc.so
libicui18n.so

签名：

export SIGN_TOOL=$OHOS_SDK_ROOT/toolchains/lib/binary-sign-tool

cd entry/libs/arm64-v8a

$SIGN_TOOL sign -inFile libkdiff3.so -outFile libkdiff3.so -selfSign 1
$SIGN_TOOL sign -inFile libicuuc.so -outFile libicuuc.so -selfSign 1
$SIGN_TOOL sign -inFile libicui18n.so -outFile libicui18n.so -selfSign 1

10. 每一步的成功标志

阶段 成功标志
SDK 准备 ohos.toolchain.cmake 存在
Qt 准备 能找到 Qt5Config.cmake 或 Qt6Config.cmake
最小 Demo 编译 生成 libqt_ohos_demo.so
ABI 检查 Machine: AArch64
HAP 壳运行 鸿蒙 PC 显示 Hello Qt 窗口
vcpkg-ohos zlib:arm64-ohos 安装成功
KDiff3 Linux 原版 ninja -C build-linux 成功
KDiff3 鸿蒙版 生成 libkdiff3.so
真机运行 主窗口能打开

11. 常见问题排查

11.1 CMake 找不到 OHOS SDK

报错类似：

Could not find OHOS SDK

检查：

echo $OHOS_SDK_ROOT
ls $OHOS_SDK_ROOT/native/build/cmake/ohos.toolchain.cmake

11.2 CMake 找不到 Qt

报错类似：

Could not find Qt6Config.cmake

检查：

echo $QT_OHOS_ROOT
find $QT_OHOS_ROOT -name "Qt6Config.cmake" -o -name "Qt5Config.cmake"

CMake 中要有：

set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE BOTH)

11.3 编译出来不是 AArch64

检查：

$OHOS_SDK_ROOT/native/llvm/bin/llvm-readelf -h libxxx.so

如果不是：

Machine: AArch64

说明你可能用了宿主机编译器，而不是 OHOS toolchain。

11.4 真机运行提示 operation not permitted

通常是没签名。

处理：

$OHOS_SDK_ROOT/toolchains/lib/binary-sign-tool sign \
  -inFile libxxx.so \
  -outFile libxxx.so \
  -selfSign 1

11.5 dlopen failed

通常是缺库。

检查：

entry/libs/arm64-v8a/

里面是否有所有 Qt runtime 和三方库。

11.6 undefined symbol

常见原因：

  • Qt5 和 Qt6 混用
  • ICU 版本不一致
  • 拷贝了 Linux x86_64 的 .so
  • 少拷贝某个依赖库

先用 llvm-readelf -h 检查每个 .so。

12. 小白建议路线

不要第一天就直接改 KDiff3。建议按这个路线：

第 1 天：搭环境，确认 SDK、Qt、CMake 路径
第 2 天：跑通最小 Qt Widgets Demo
第 3 天：跑通 HAP 壳加载 libqt_ohos_demo.so
第 4 天：跑通 vcpkg zlib:arm64-ohos
第 5 天：拉 KDiff3，Linux 原版编译通过
第 6 天：修改 KDiff3 CMake，生成 libkdiff3.so
第 7 天：开始裁剪 KIO、KXmlGui、KConfig、KI18n

如果你能做到：

最小 Qt Demo 在鸿蒙 PC 上显示窗口
vcpkg 能编出 arm64-ohos 的 zlib
KDiff3 能在 Linux 上原版编译

那你已经完成了 60% 的基础工作。后面 KDiff3 的适配，主要就是一个个处理 KDE 依赖和平台差异。

13. 参考资料

本教程主要参考当前资料目录中的：

  • 知识库/使用 vcpkg 为鸿蒙（HarmonyOS _ OHOS）下载与安装三方库实践指南.md
  • 知识库/HarmonyOS鸿蒙三方库移植：选 vcpkg 还是 lycium_plusplus？两种“框架化”方案对比.md
  • 知识库/鸿蒙 PC 三方库移植实战 · 直播课件（详细教案）.md
  • KDiff3鸿蒙PC适配实操教程.md

外部资料：

  • Qt vcpkg-ohos 介绍：https://www.qt.io/blog/building-libraries-for-harmonyos-with-vcpkg
  • Qt for HarmonyOS CMake / DevEco 指南：https://wiki.qt.io/Qt_for_HarmonyOS/user_development/deveco_cmake_guide_cross_compile_zh
  • KDiff3 源码：https://invent.kde.org/sdk/kdiff3
  • KDiff3 GitHub 镜像：https://github.com/KDE/kdiff3

14. 最后记一句

小白做这类适配，最重要的是不要把所有问题混在一起。
每一步都保存成功截图、命令、日志。这样后面遇到问题时，能快速判断是环境问题、依赖问题、CMake 问题，还是 KDiff3 自身代码适配问题。

# qt # harmonyos # 开发语言
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

HarmonyOS 6 悬浮导航 + 沉浸光感：打造鸿蒙智能体驱动的沉浸式AR导航助手

avatar 人工智能6S服务平台
cover

全国首家面向制造业的开源鸿蒙创新中心正式成立

avatar 人工智能6S服务平台
cover

CANN-昇腾NPU-自定义算子注册-怎么让ATB用你的算子

avatar 人工智能6S服务平台