代码在IDE运行正常，部署后提示QtQuick.Controls模块未安装如何解决？

问题描述 #

代码在IDE中运行时弹出"success"提示，但使用windeployqt部署程序后，出现错误提示：module "QtQuick.Controls" is not installed。注：未使用任何资源文件，实际QML内容简短，后续可能自动生成，需解决该部署报错问题。

相关代码 #

CMakeLists.txt #

cmake_minimum_required(VERSION 3.5)

project(qq VERSION 0.1 LANGUAGES CXX)

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

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Widgets)
find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS QuickWidgets)

set(PROJECT_SOURCES
    main.cpp
)

if(${QT_VERSION_MAJOR} GREATER_EQUAL 6)
    qt_add_executable(qq
        MANUAL_FINALIZATION
        ${PROJECT_SOURCES}
    )
else()
    add_executable(qq
        ${PROJECT_SOURCES}
    )
endif()

target_link_libraries(
    qq
    PRIVATE Qt${QT_VERSION_MAJOR}::QuickWidgets
)

if(QT_VERSION_MAJOR EQUAL 6)
    qt_finalize_executable(qq)
endif()

main.cpp #

#include <QApplication>
#include <QMessageBox>
#include <QtQuickWidgets>

#define QML_TEST R"(
import QtQuick.Controls
Button {}
)"

int main(int argc,char *argv[]) {
    QApplication app(argc,argv);
    QQuickWidget qkwTest;
    qkwTest.setSource(QUrl(
        QStringLiteral("data:text/plain;,%1").
        arg(QStringLiteral(QML_TEST).toUtf8().toPercentEncoding())
    ));
    if(!qkwTest.rootObject())
        for(const auto &e:qkwTest.errors())
            QMessageBox::information(nullptr,"error",e.description());
    else
        QMessageBox::information(nullptr,QString(),"success");
    app.exit();
}

解决方案 #

1. 完善CMake依赖配置 #

代码依赖QtQuick.Controls模块，但当前CMakeLists仅声明了QuickWidgets依赖，需补充对应组件：

• 针对Qt5，添加QuickControls2（对应QtQuick.Controls 2.x版本，为当前默认版本）：
  修改find_package和target_link_libraries部分：

  find_package(QT NAMES Qt5 REQUIRED COMPONENTS Widgets)
  find_package(Qt5 REQUIRED COMPONENTS QuickWidgets QuickControls2)
  
  target_link_libraries(
      qq
      PRIVATE Qt5::QuickWidgets
              Qt5::QuickControls2
  )
  

• 针对Qt6，同样补充QuickControls2组件：

  find_package(QT NAMES Qt6 REQUIRED COMPONENTS Widgets)
  find_package(Qt6 REQUIRED COMPONENTS QuickWidgets QuickControls2)
  
  target_link_libraries(
      qq
      PRIVATE Qt6::QuickWidgets
              Qt6::QuickControls2
  )
  

2. 手动指定windeployqt参数 #

由于QML代码内嵌在C++中，windeployqt自动检测无法识别到依赖模块，需手动指定部署内容：

• 执行部署命令时添加--modules参数指定模块：

  # Qt5
  windeployqt --modules QtQuick.Controls2 <你的可执行文件路径>
  # Qt6
  windeployqt --modules QtQuick.Controls2 <你的可执行文件路径>
  

• 或通过--qmldir参数指向Qt安装目录中的对应模块路径，确保工具能找到相关QML文件：

  # Qt5示例路径
  windeployqt --qmldir "C:\Qt\5.15.2\mingw81_64\qml\QtQuick\Controls.2" <你的可执行文件路径>
  # Qt6示例路径
  windeployqt --qmldir "C:\Qt\6.5.0\mingw81_64\qml\QtQuick\Controls" <你的可执行文件路径>
  

3. 匹配windeployqt版本 #

必须使用与编译程序时相同Qt版本的windeployqt工具，避免版本不匹配导致部署文件错误或缺失。

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