Qt6运行时QML导入路径问题：嵌套目录模块加载异常

问题场景 #

• 当MyApp直接包含MyQmlModule时，仅在主项目CMakeLists.txt中链接库即可加载QML模块，无需额外操作。
• 当在MyApp与MyQmlModule之间加入QmlModules目录后，模块加载失败，必须做两项操作：
  • 在模块的CMakeLists.txt中设置QML_IMPORT_PATH为${CMAKE_CURRENT_BINARY_DIR}/../，让Qt Creator识别模块以支持语法补全和高亮；
  • 在main.cpp中手动调用engine->addImportPath(${CMAKE_CURRENT_BINARY_DIR})才能加载模块。

核心疑问 #

1. 希望通过CMake配置覆盖运行时导入路径，避免在生产代码中手动添加导入路径。
2. 疑惑qt_add_qml_module是否会生成编译到插件中的.qrc文件，以及是否需要将资源与插件一同部署。

示例代码与目录结构 #

目录结构 #

testapp
├── CMakeLists.txt
├── main.cpp
├── Main.qml
└── modules
    └── mymodule
        ├── CMakeLists.txt
        └── CustomQMl.qml

主项目CMakeLists.txt #

cmake_minimum_required(VERSION 3.16)

project(testapp VERSION 0.1 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 6.5 REQUIRED COMPONENTS Quick)

qt_standard_project_setup(REQUIRES 6.5)

qt_add_executable(apptestapp
    main.cpp
)

qt_add_qml_module(apptestapp
    URI testapp
    VERSION 1.0
    QML_FILES Main.qml
)

set_target_properties(apptestapp PROPERTIES
    MACOSX_BUNDLE_GUI_IDENTIFIER my.example.com
    MACOSX_BUNDLE_BUNDLE_VERSION ${PROJECT_VERSION}
    MACOSX_BUNDLE_SHORT_VERSION_STRING ${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}
    MACOSX_BUNDLE TRUE
    WIN32_EXECUTABLE TRUE
)

target_link_libraries(apptestapp
    PRIVATE Qt6::Quick
    mymodule
)

install(TARGETS apptestapp
    BUNDLE DESTINATION .
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)
# adding custom module
add_subdirectory(modules/mymodule)

main.cpp #

#include <QGuiApplication>
#include <QQmlApplicationEngine>

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

  QQmlApplicationEngine engine;
  QObject::connect(
      &engine, &QQmlApplicationEngine::objectCreationFailed, &app,
      []() { QCoreApplication::exit(-1); }, Qt::QueuedConnection);

  // have to add this import path or it wont load module
  engine.addImportPath(
      "/home/developer/testapp/builds/"
      "build-testapp-Desktop_Qt_6_5_1_GCC_64bit-Debug/modules");
  engine.loadFromModule("testapp", "Main");

  return app.exec();
}

模块CMakeLists.txt #

cmake_minimum_required(VERSION 3.16)

project(MyModuleProject VERSION 0.1 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 6.5 REQUIRED COMPONENTS Quick)

qt_standard_project_setup(REQUIRES 6.5)

qt_add_qml_module(mymodule
    URI mymodule
    VERSION 1.0
    QML_FILES CustomQml.qml
)

set_target_properties(mymodule PROPERTIES
    MACOSX_BUNDLE_GUI_IDENTIFIER my.example.com
    MACOSX_BUNDLE_BUNDLE_VERSION ${PROJECT_VERSION}
    MACOSX_BUNDLE_SHORT_VERSION_STRING ${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}
    MACOSX_BUNDLE TRUE
    WIN32_EXECUTABLE TRUE
)

set(QML_DIRS "${QML_IMPORT_PATH}")
list(APPEND QML_DIRS "${CMAKE_CURRENT_BINARY_DIR}/../")
set(QML_IMPORT_PATH "${QML_DIRS}" CACHE STRING "Controls" FORCE)

问题分析与解决方案 #

1. 为什么手动添加导入路径是必要的？ #

CMake中的QML_IMPORT_PATH仅用于Qt Creator的IDE识别（语法补全、高亮），不会自动传递给运行时。运行时QML引擎的导入路径默认包含：

• 应用程序可执行文件所在目录
• Qt自带QML模块路径
• 系统环境变量QML2_IMPORT_PATH指定的路径

当模块被放在modules子目录下时，构建后的模块插件会生成在build/modules/mymodule目录，不在引擎默认搜索路径内，因此需要手动添加。

2. 如何通过CMake自动配置运行时导入路径，避免硬编码？ #

可以通过CMake传递编译定义，将模块的构建/安装路径注入到代码中，无需硬编码绝对路径：

修改主项目CMakeLists.txt：

在target_link_libraries之后添加：

# 传递模块构建路径给主程序（调试阶段）
target_compile_definitions(apptestapp PRIVATE
    MY_MODULE_IMPORT_PATH="$<TARGET_FILE_DIR:mymodule>/.."
)
# 安装时设置导入路径（发布阶段）
install(CODE "
    set(QML_IMPORT_PATH \"\${CMAKE_INSTALL_PREFIX}/lib\")
" COMPONENT Runtime)

修改main.cpp：

替换硬编码的addImportPath为：

// 使用CMake传递的编译定义
engine.addImportPath(MY_MODULE_IMPORT_PATH);

这样调试时会自动使用模块的构建目录上级路径，发布安装后会指向lib目录（需确保模块安装到对应位置）。

3. qt_add_qml_module与资源文件的关系 #

• qt_add_qml_module默认会将QML文件编译到插件的资源中（生成内部.qrc），此时无需单独部署QML文件，因为它们已经嵌入到插件库中。
• 如果使用NO_RESOURCE_TARGET_PATH或手动禁用资源生成，才需要将QML文件与插件一同部署，此时要确保QML文件在插件的搜索路径内。

额外优化：让模块自动被引擎识别 #

另一种方式是将模块安装到Qt的系统模块路径，或通过QT_QML_MODULE_PATH环境变量指定，但更可靠的是通过CMake配置目标的IMPORTED_LOCATION和安装规则，确保运行时能找到插件。

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