Windows下PySide2加载C++ QML插件失败：找不到指定模块

问题本质 #

这不是绑定的问题——你的插件在C++程序里能正常运行，说明插件本身的功能和QML绑定逻辑没问题，核心原因是Windows系统的DLL依赖搜索机制和Linux/macOS不同，Python进程的环境路径没包含插件依赖的动态库路径。

具体排查修复步骤 #

• 检查插件的依赖DLL
  用Dependency Walker或者Qt自带的windeployqt工具扫描plugin.dll，确认它依赖的Qt核心库（比如Qt5Core.dll、Qt5Qml.dll）和MinGW运行库（比如libgcc_s_seh-1.dll、libstdc++-6.dll）是否能被Python进程找到。
  C++程序运行时，通常会自动把Qt和MinGW的bin目录加入搜索路径，但Python进程的PATH可能没包含这些路径，导致加载插件时找不到依赖。

• 手动添加DLL搜索路径到Python进程
  在main.py最开头加入代码，把Qt和MinGW的bin目录加到系统PATH里：

  import os
  import sys
  
  # 替换成你实际的Qt5.15.2 MinGW版本bin路径
  qt_bin = "D:/Qt/5.15.2/mingw81_64/bin"
  # 替换成你MinGW6.1.0的bin路径
  mingw_bin = "D:/mingw6.1.0/bin"
  
  os.environ['PATH'] = f"{qt_bin};{mingw_bin};{os.environ['PATH']}"
  

  注意路径要用斜杠/或者双反斜杠\\，避免转义问题。

• 确认QML模块路径配置正确
  在Python代码里务必把项目根目录（D:/untitled）添加到QML引擎的搜索路径：

  from PySide2.QtQml import QQmlApplicationEngine
  
  engine = QQmlApplicationEngine()
  engine.addImportPath("D:/untitled")
  engine.load("main.qml")
  

  同时检查a/plugin/video/qmldir的格式是否正确：

  module a.plugin.video
  plugin plugin
  

  这里的plugin要和你的DLL文件名（去掉.dll后缀）完全一致。

• 验证架构匹配性
  确保plugin.dll是MinGW编译的64位版本，同时你的Python也是64位——32位和64位混合会直接导致加载失败。

关于绑定的说明 #

不需要为plugin.dll创建额外的Python绑定。你的插件是标准的Qt QML C++插件，PySide2作为Qt的Python绑定，天然支持加载这类插件。Linux和macOS能正常运行，是因为它们的动态库搜索机制会自动从标准路径或库的内置RPATH找到依赖，而Windows完全依赖PATH环境变量和当前工作目录。

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