Windows下PyQGIS独立应用导入qgis.core报无模块问题咨询

核心问题根因 #

QGIS 3.22 Windows安装包采用OSGeo4W封装结构，官方文档示例里的<qgispath>并非QGIS一级安装根目录，且仅配置PYTHONPATH不足以完成环境初始化，你遇到的报错由路径配置错误、缺失必要环境变量、Python版本不匹配三类问题共同导致。

必须完成的配置步骤 #

• 第一步：匹配Python运行环境
  QGIS 3.22内置Python版本为64位Python 3.9，独立Python环境必须和该版本、位数完全一致。PyQGIS包含C扩展模块，跨大版本Python（3.8/3.10及以上）无法加载，32位Python也无法兼容64位QGIS的库文件。
• 第二步：配置正确的环境变量
  默认安装路径基准为C:\Program Files\QGIS 3.22.x（替换x为你实际安装的小版本号），需配置3个环境变量，注意不要写错目录名（3.22为LTR长期支持版，核心程序目录带-ltr后缀）：
  • QGIS_PREFIX_PATH：值为C:\Program Files\QGIS 3.22.x\apps\qgis-ltr，该变量是QGIS 3.16之后版本必须配置项，用于告知PyQGIS资源、投影库、插件的存储位置，老版官方文档未提及该配置。
  • PYTHONPATH：需添加两个路径，而非单个路径：
    1. C:\Program Files\QGIS 3.22.x\apps\qgis-ltr\python（这就是官方示例中提到的python文件夹，你之前在一级安装根目录查找属于路径层级错误）
    2. C:\Program Files\QGIS 3.22.x\apps\Python39\Lib\site-packages（用于加载PyQGIS依赖的PyQt5、GDAL等第三方库）
  • PATH：需将以下路径添加到变量值最前端，避免系统其他版本的GDAL、Qt库冲突：
    1. C:\Program Files\QGIS 3.22.x\apps\qgis-ltr\bin
    2. C:\Program Files\QGIS 3.22.x\bin
    3. C:\Program Files\QGIS 3.22.x\apps\Python39
    4. C:\Program Files\QGIS 3.22.x\apps\Qt5\bin
• 第三步：生效环境变量并验证
  配置完成后必须完全关闭当前打开的终端、IDE，重新启动后才会加载新的环境变量，在已运行的进程中不会读取更新后的变量值。
• 第四步：代码中初始化QGIS实例
  独立应用不能直接导入模块执行业务逻辑，必须先初始化QGIS核心实例，最小可运行示例：

  from qgis.core import QgsApplication, Qgis
  # 非GUI模式初始化，第二个参数设为True则启动GUI相关组件
  qgs_app = QgsApplication([], False)
  qgs_app.initQgis()
  
  # 业务逻辑写在初始化之后
  print(f"加载PyQGIS成功，当前QGIS版本：{Qgis.QGIS_VERSION}")
  
  # 程序退出前释放资源
  qgs_app.exitQgis()
  

之前操作的常见误区 #

• 误将QGIS一级安装根目录当做官方示例中的<qgispath>，实际该路径对应apps/qgis-ltr子目录，一级根目录下本身不存在python文件夹。
• 错误将apps\qgis\python\qgis加入PYTHONPATH：该路径是qgis包的内部目录，加入搜索路径后Python无法识别顶层qgis包的初始化文件，必然报模块不存在错误。
• 漏配QGIS_PREFIX_PATH：即使模块文件被找到，PyQGIS也会因找不到资源文件无法完成加载。
• 未匹配Python版本：这是最高发的隐形问题，跨版本Python无法加载针对固定Python版本编译的C扩展模块，无论怎么配置路径都无法成功导入。

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