PyInstaller打包含QGIS GUI模块的独立应用报错求助

乱码导入错误的原因 #

这个RuntimeError本质是QGIS的_gui.pyd扩展模块依赖的Qt自定义类型/私有类型未被PyInstaller正确识别和打包，加上打包过程中的编码解析问题，导致类型名显示为乱码����。核心问题是QGIS GUI模块依赖的资源、Qt子模块、QGIS内部插件等未完全纳入打包范围，导致运行时无法找到对应类型。

正确打包步骤及需添加的QGIS文件 #

1. 确保环境加载正确 #

必须通过QGIS自带的批处理文件（如qgis-ltr.bat）启动PyCharm或命令行，让环境变量完整加载QGIS的依赖路径，虚拟环境需继承该环境的PATH变量，否则PyInstaller无法找到QGIS的底层依赖。

2. 编写Spec文件的关键配置 #

在自定义的spec文件中补充以下配置：

• 添加核心依赖文件：
  在datas列表中加入QGIS安装目录的以下资源：

  datas=[
      # 打包QGIS的资源文件（样式、图标等）
      (r'C:\Program Files\QGIS 3.XX\resources', 'resources'),
      # 打包QGIS和Qt的核心DLL
      (r'C:\Program Files\QGIS 3.XX\bin\qgis_core.dll', '.'),
      (r'C:\Program Files\QGIS 3.XX\bin\qgis_gui.dll', '.'),
      (r'C:\Program Files\QGIS 3.XX\bin\Qt5Gui.dll', '.'),
      (r'C:\Program Files\QGIS 3.XX\bin\Qt5Widgets.dll', '.'),
      (r'C:\Program Files\QGIS 3.XX\bin\Qt5PrintSupport.dll', '.'),
      (r'C:\Program Files\QGIS 3.XX\bin\Qt5Svg.dll', '.'),
      # 打包QGIS的类型提示文件
      (r'C:\Program Files\QGIS 3.XX\Python\Lib\site-packages\qgis\*.pyi', 'qgis'),
  ]
  

• 补充隐藏导入模块：
  在hiddenimports中加入GUI模块依赖的所有子模块：

  hiddenimports=[
      'qgis._gui',
      'qgis.core',
      'qgis.gui',
      'PyQt5.QtGui',
      'PyQt5.QtWidgets',
      'PyQt5.QtCore',
      'PyQt5.QtPrintSupport',
      'PyQt5.QtSvg',
      'PyQt5.QtXml'
  ]
  

• 配置扩展模块路径：
  在pathex中加入QGIS的Python模块路径，确保PyInstaller能找到QGIS的包：

  pathex=[
      r'C:\Program Files\QGIS 3.XX\Python\Lib\site-packages',
      # 你的项目路径
      r'C:\your_project_path'
  ]
  

3. 打包与验证 #

• 执行打包命令：pyinstaller your_app.spec，避免直接用pyinstaller your_app.py跳过自定义配置。
• 打包完成后，检查输出目录：
  • 根目录下存在所有添加的QGIS和Qt DLL文件；
  • qgis子目录包含_core.pyd、_gui.pyd及所有.pyi类型提示文件；
  • resources子目录完整包含QGIS的资源文件。

额外排查要点 #

• 若仍报错，运行打包程序时添加调试参数：your_app.exe --debug all，根据日志提示补充缺失的模块或DLL到spec配置中；
• 确保虚拟环境的PyQt5版本与QGIS自带的PyQt5版本完全一致，版本不兼容会导致类型匹配失败；
• 检查QGIS的bin目录是否被正确加入系统PATH，打包时PyInstaller需通过该路径识别依赖。

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