Qt6 CMake开发QML时提示module "QtQuick.Controls"未安装如何解决

解决方案步骤 #

1. 修正CMakeLists.txt配置 #

你之前直接将QML文件放到qt_add_executable中的写法无法让Qt识别QML模块依赖，需要使用Qt6官方指定的qt_add_qml_module管理QML资源，配置示例如下：

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED True)

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

find_package(Qt6 REQUIRED COMPONENTS Core Gui Quick QuickControls2)

qt_add_executable(nameHere
    src/main.cpp
)

# 新增QML模块配置
qt_add_qml_module(nameHere
    URI myApp
    VERSION 1.0
    QML_FILES gui/main.qml
)

target_link_libraries(nameHere PRIVATE Qt6::Core Qt6::Gui Qt6::Quick Qt6::QuickControls2)

# 开启Windows下自动部署所有Qt依赖
if(WIN32)
    set_target_properties(nameHere PROPERTIES
        WIN32_EXECUTABLE TRUE
    )
    install(TARGETS nameHere
        BUNDLE DESTINATION .
        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
    )
    qt_generate_deploy_qml_app_script(
        TARGET nameHere
        OUTPUT_SCRIPT deploy_script
        NO_UNSUPPORTED_PLATFORM_ERROR
    )
    install(SCRIPT ${deploy_script})
endif()

2. 修正main.cpp的QML加载逻辑 #

QQuickView仅支持根元素为Item的QML文件，你用的ApplicationWindow属于窗口类型，需要用QQmlApplicationEngine加载：

#include <QGuiApplication>
#include <QQmlApplicationEngine>

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

    QQmlApplicationEngine engine;
    // 路径和上一步qt_add_qml_module的URI对应
    engine.load(QUrl("qrc:/myApp/gui/main.qml"));
    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}

3. 执行install目标完成自动部署 #

在Visual Studio生成的解决方案中，找到CMakePredefinedTargets分组下的INSTALL项目，右键点击生成，所有依赖的Qt DLL、QML模块文件（含QtQuick.Controls所需的qmldir、风格子模块等）都会自动复制到build/install/bin目录下，直接运行该目录下的exe即可。

4. 手动调用windeployqt的正确方式 #

如果需要手动部署，必须指定QML文件所在目录才能让windeployqt识别QML依赖：

windeployqt.exe --qmldir 你的项目根目录/gui 你的exe完整路径

你之前手动复制Qt6QuickControls2.dll无效的原因是：QML模块不止包含动态库，还需要配套的qmldir描述文件、类型定义、风格组件等文件，仅复制DLL无法被QML引擎识别为有效模块。CMake之前仅复制基础Qt DLL是因为默认只处理C++链接层面的依赖，不会自动识别QML模块依赖，需要添加QML部署配置才会触发相关文件的复制。

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