Qt 鸿蒙PC开发环境搭建（ Mac ）

徐建国

发布于 2025-11-29 15:08:55

文章被收录于专栏：个人路线个人路线

Qt 鸿蒙开发环境搭建 Mac 篇

概述

本文档将指导您如何在 Mac 平台上配置 Qt 鸿蒙应用开发环境。

声明

本文档中使用的 Qt for OpenHarmony SDK 是由 OpenHarmony SIG 社区基于 Qt 5.15 独立开发和维护的项目，非 Qt 官方版本。

文档适用范围

OpenHarmony API 15 (5.0.3)及以上版本
Qt for OpenHarmony (基于 Qt 5.15)
DevEco Studio 5.0.5 及以上版本

前置条件

具备基础的 Qt 开发知识
了解 OpenHarmony 应用开发基础

基于 DevEco Studio 的 Qt 应用创建

1. DevEco Studio 下载与安装

官方下载地址：DevEco Studio 官网[1]
对于需要使用特定版本 DevEco Studio 的开发者，可通过以下页面获取历史版本[2]。

注意事项：

推荐使用最新稳定版本以获得最佳兼容性
历史版本可能不支持最新的 OpenHarmony API
下载前请确认版本与你的项目需求匹配

2. 安装步骤

在安装界面中，将“DevEco-Studio.app”拖拽到“Applications”中，等待安装完成。

img

3. Qt SDK 下载与配置

3.1 获取 Qt for OpenHarmony SDK

下载地址：Qt for OpenHarmony SDK[3]
版本说明：基于 Qt 5.15 开发，由 OpenHarmony SIG 社区维护
推荐版本：建议使用最新版本

image-20251104150550972

在终端执行以下命令，解压 Qt SDK 到指定目录（当然你也可以直接解压并拷贝）。

tar -xf Qt5.15.12_alpha_v7_arm64-v8a_openharmony_ndk_5.0.3.135_community_macos.tar.gz -C ~/QtForOpenHarmony

image-20251104151621833

在终端继续执行以下命令，验证 Qt for OpenHarmony 的安装。

cd bin
./qmake -query

image-20251104151558132

打印QMAKE_XSPEC:oh-clang即为 Qt for OpenHarmony 版本，Qt for OpenHarmony SDK 安装完成。

至此基于 DevEco Studio 的 Qt for OpenHarmony 应用开发环境搭建完毕。

创建一个 Qt Quick 工程

1. 打开 DevEco Studio 新建项目，选择 Native C++类型的模板工程创建空工程。

image-20251104151945614

修改工程名称，并根据实际情况选择工程最终需要运行的设备类型，Bundle name 为应用唯一标识需确保不和其它应用冲突，Save location 可自行选择工程路径，Compatible SDK 可根据设备的 API 版本号自行修改，主模块名称可自行修改:

image-20251104152238613

创建 OpenHarmony 工程（可选）

在完成创建 HarmonyOS 工程[4]后，根据如下操作修改工程级 build-profile.json5 文件中相关字段：

"products": [
  {
    "name": "default",
    "signingConfig": "default",
    "compileSdkVersion": 18,    //指定OpenHarmony应用编译时的版本，当前以API 18为例
    "targetSdkVersion": 18,     //指定OpenHarmony应用运行所需的目标SDK版本，当前以API 18为例
    "compatibleSdkVersion": 18, //指定OpenHarmony应用兼容的最低版本，当前以API 18为例
    "runtimeOS": "OpenHarmony",
  }
]

在工程级 build-profile.json5 文件添加compileSdkVersion字段。
将compatibleSdkVersion、compileSdkVersion、targetSdkVersion（若有）字段赋值为数值类型。
将 runtimeOS 从"HarmonyOS"修改为**"OpenHarmony"**。

单击 Sync Now 进行同步。在 Sync Check 弹窗中点击Yes，同意将 module.json5/config.json 文件中的 phone 切换为 OpenHarmony 支持的 default 类型，并删除在 OpenHarmony 不适用的其他设备类型，同步成功无其他报错则工程创建完成。

image-20251104152748745

2. Qt Quick 工程配置

修改基础配置 ：找到创建工程时使用的模块对应目录下的build-profile.json5文件，修改arguments字段(指定 Qt SDK 路径)和abiFilters字段(最终运行的设备架构)：

"externalNativeOptions": {
  "path": "./src/main/cpp/CMakeLists.txt",
  "arguments": "-DQT_PREFIX=/Users/baixm/QtForOpenHarmony",
  "cppFlags": "",
  "abiFilters": ["arm64-v8a"]
}

image-20251104153212123

拷贝 ets 文件依赖： 将 Qt SDK 目录下的openharmony/qtbase所有目录复制替换到工程模块下的src/main/ets目录下：

image-20251104153509920

image-20251104153416313

拷贝 qml 资源及库文件依赖： 将 Qt SDK 目录下的qml目录分别拷贝到工程模块下的libs/arm64-v8a(qml 库依赖)和src/main/resources/resfile(qml 资源文件依赖)目录下(resfile 目录需要自己创建)，并将 Qt SDK 目录下的plugins/platforms/libplugins_platforms_qopenharmony.so拷贝到工程模块下的libs/arm64-v8a目录下：

image-20251104154231996

image-20251104154414669

模块module.json5文件配置 UIAbility 组件，这是应用的入口。"launchType": "specified"表示该 UIAbility 为指定实例模式，若工程需要打开多个窗口时，应将launchType指定为specified。配置 module.json5 文件内容如下图所示。

image-20251104154612427

3. 编写一个 Qt Quick 的 Hello World 工程

移除napi_init.cpp文件，修改CMakeLists.txt文件，并添加main.cpp、main.qml以及qml.qrc文件。

// CMakeLists.txt
# the minimum version of CMake.
cmake_minimum_required(VERSION 3.5.0)
project(QtForHOSample)

set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTORCC ON)

set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})

list(APPEND CMAKE_FIND_ROOT_PATH ${QT_PREFIX})
include_directories(${NATIVERENDER_ROOT_PATH}
                    ${NATIVERENDER_ROOT_PATH}/include)

find_package(QT NAMES Qt5 Qt6 REQUIRED COMPONENTS Core Widgets)
find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Concurrent Gui Network Qml Quick QuickControls2 Widgets QuickTemplates2 QmlWorkerScript)

add_library(entry SHARED main.cpp qml.qrc)
target_link_libraries(entry PRIVATE Qt${QT_VERSION_MAJOR}::Concurrent
Qt${QT_VERSION_MAJOR}::Core
Qt${QT_VERSION_MAJOR}::Gui
Qt${QT_VERSION_MAJOR}::Network
Qt${QT_VERSION_MAJOR}::Qml
Qt${QT_VERSION_MAJOR}::Quick
Qt${QT_VERSION_MAJOR}::Widgets
Qt${QT_VERSION_MAJOR}::QuickControls2
Qt${QT_VERSION_MAJOR}::QuickTemplates2
Qt${QT_VERSION_MAJOR}::QmlWorkerScript
Qt${QT_VERSION_MAJOR}::QOpenHarmonyPlatformIntegrationPlugin
)

main.qml

// main.qml
import QtQuick 2.15
import QtQuick.Window 2.15

Window {
    width: 400
    height: 300
    visible: true
    title: "Hello World QML"

    Rectangle {
        width: 300
        height: 200
        color: "lightblue"
        anchors.centerIn: parent

        Text {
            text: "Hello World!"
            font.pixelSize: 32
            color: "darkblue"
            anchors.centerIn: parent
        }
    }
}

qml.qrc 文件

<?xml version="1.0" encoding="UTF-8"?>
<RCC>
    <qresource prefix="/">
        <file>main.qml</file>
    </qresource>
</RCC>

main.cpp

// main.cpp
#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQmlApplicationEngine engine;

    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}