Qt中如何正确链接自定义QML模块？

一、当前配置的修复方案 #

你遇到的“模块未安装”错误，核心是QML模块的依赖声明和链接逻辑不完整，按以下步骤调整：

1. 修正主项目CMakeLists.txt #

在主模块的qt6_add_qml_module中添加对Ui模块的依赖声明，同时确保链接正确的目标：

find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml)

add_subdirectory(Ui)

qt6_add_qml_module(Application 
    URI Application 
    QML_FILES main.qml 
    NO_RESOURCE_TARGET_PATH
    DEPENDENCIES Ui  # 声明依赖Ui模块，让Qt自动处理QML导入逻辑
)
target_link_libraries(Application PRIVATE Qt6::Gui Qt6::Qml Ui)

2. 静态构建的额外配置（如果使用静态Qt） #

如果是静态编译Qt，需要确保静态插件自动注册，在主CMakeLists开头添加：

set(BUILD_SHARED_LIBS OFF)
set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/qml)

二、qt_add_qml_module的两个目标说明 #

qt6_add_qml_module会生成两个目标，作用和链接规则如下：

• 后台库（如Ui）：包含模块的C++逻辑（若有）和QML模块的注册代码。无论是静态还是动态构建，链接这个目标都是最稳妥的方式——它能让QML引擎在启动时就识别到你的自定义模块。
• 插件（如Uiplugin）：仅在动态构建时生成的动态库文件。QML引擎会在运行时扫描预设路径加载它，但如果没有正确配置搜索路径，就会出现“模块未安装”错误。静态构建时，这个插件会被嵌入到后台库中，无需单独处理。

总结链接规则：

• 静态构建：直接链接后台库（如Ui）即可，插件会自动嵌入并注册。
• 动态构建：优先通过DEPENDENCIES声明模块依赖，或者确保插件输出目录在QML引擎的搜索路径中（比如设置QT_QML_MODULE_IMPORT_PATH），也可以直接链接后台库跳过插件扫描。

三、标准Qt模块无需手动链接的原因 #

Qt官方模块（如QtQuick、QtQuick.Controls）的依赖和注册逻辑已经被Qt的构建系统自动化处理：

1. 当你find_package(Qt6 REQUIRED COMPONENTS Qml)时，CMake会自动引入QtQuick等核心模块的依赖关系，相关库会被隐式链接到你的目标中。
2. 这些模块的注册代码已经集成到Qt的核心库，或者Qt会自动配置插件搜索路径，无需手动声明链接或路径。

内容的提问来源于stack exchange，提问作者Mark