自定义C++ QML插件无法被测试应用加载求助

问题现象 #

编译C++ QML插件库后，测试应用编译通过但运行时报错：

QQmlApplicationEngine failed to load component
qrc:/main.qml:3:1: module "MyPlugin" is not installed

环境：Qt 5.15.7、Qt Creator 5.0.3、Ubuntu 18.04

解决方案 #

1. 配置测试项目的QML导入路径 #

修改TestPlugin.pro文件，将QML_IMPORT_PATH指向插件所在的目录：

# Additional import path used to resolve QML modules in Qt Creator's code model
QML_IMPORT_PATH += ../pluginFiles

该配置让Qt Creator的代码模型识别模块，同时帮助QML引擎在运行时查找插件。

2. 调整插件的目录结构（关键） #

QML模块要求插件与qmldir文件必须放在以模块名命名的子目录中。修改CreatePlugin.pro的DESTDIR：

DESTDIR = ../pluginFiles/MyPlugin

编译后，插件库（libCreatePlugin.so）和qmldir会输出到pluginFiles/MyPlugin目录，完全符合QML模块的查找规则。

若不想修改DESTDIR，也可手动在pluginFiles目录下创建MyPlugin子文件夹，将编译好的插件库和qmldir文件移入其中。

3. 确保运行时环境变量正确 #

Ubuntu下Qt需要明确QML插件的查找路径，可通过两种方式配置：

• 终端临时运行：

  export QML2_IMPORT_PATH=/绝对路径/to/pluginFiles
  ./TestPlugin
  

• Qt Creator运行配置：
  打开项目「运行」配置，在「环境」中添加变量QML2_IMPORT_PATH，值为pluginFiles目录的绝对路径（或确保程序运行时可访问的相对路径）。

4. 验证插件文件完整性 #

确认以下文件存在且路径正确：

• pluginFiles/MyPlugin/libCreatePlugin.so（编译生成的插件库）
• pluginFiles/MyPlugin/qmldir（模块描述文件，内容需与配置一致）

可选：全局安装插件（适合正式发布） #

若希望插件被所有Qt应用识别，可执行插件项目的安装命令：

cd CreatePlugin/build
sudo make install

此操作会将插件和qmldir安装到Qt的系统QML目录（$$[QT_INSTALL_QML]/MyPlugin），无需额外配置导入路径。

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