PyQGIS常见报错排查与解决
PyQGIS 常见报错主要集中在三类：独立脚本里 import qgis.core 失败、图层加载后无效（控制台常见 “Layer failed to load!”），以及初始化顺序或 QGIS 3/4（Qt5/Qt6）环境不一致。排查时先分清是在 QGIS 内 Python 控制台还是独立进程，再按「模块与库路径 → 前缀路径与 initQgis → 数据源 URI 与提供者 → 版本/API」逐项核对。截至 2026 年 11 月，官方版本文件标明可用 LTR 为 3.44.15、最新可用版本为 4.2.3；QGIS 4 已基于 Qt6/PyQt6，脚本和插件要按所装版本对照 API，不要混用 3.x 习惯硬套到 4.x。
导入失败：找不到 qgis.core 或动态库
在 QGIS 外跑脚本时，系统若不知道 Python 模块和共享库位置，会直接报 ImportError: No module named qgis.core；模块找到后仍可能因找不到 libqgis_core 一类动态库再失败。官方手册给出的处理是设环境变量，把安装前缀换成你本机路径（可在已打开的 QGIS 控制台用 QgsApplication.prefixPath() 查看）。
| 平台 | Python 模块路径（PYTHONPATH） | 库搜索路径 |
|---|---|---|
| Linux | export PYTHONPATH=/<qgispath>/share/qgis/python | export LD_LIBRARY_PATH=/<qgispath>/lib |
| Windows | set PYTHONPATH=c:\<qgispath>\python | 把 bin 与 apps\<qgisrelease>\bin 加入 PATH（如 qgis-ltr、qgis、qgis-dev） |
| macOS | export PYTHONPATH=/<qgispath>/Contents/Resources/python | 按本机安装布局配置库路径 |
验收标准：同一终端里能 import qgis.core，且不再出现缺共享库的 ImportError。安装包与版本可先对照官方 QGIS 版本 LTR 文本 再下载对应构建。脚本文件名不要叫 qgis.py，否则会遮蔽绑定包导致“怎么设路径都导入失败”。
- 优先在本机已安装的 QGIS 自带 Python 环境里跑，减少路径拼错。
- 用 PYQGIS_STARTUP 指向清理脚本时，注意它会在 QGIS 初始化完成前执行，适合隔离冲突的系统 Python 路径。
- 从插件仓库下载现成插件看源码，是官方推荐的写法学习方式，比凭空猜 API 更稳。
图层加载失败：isValid 为假与提供者写错
矢量用 QgsVectorLayer(数据源, 图层名, 提供者名)，栅格用 QgsRasterLayer(路径, 显示名)。构造失败时通常仍返回图层对象，但 isValid() 为假；用 iface.addVectorLayer(…) 时失败会返回 None（应用 if not vlayer 判断）。iface 只存在于正在运行的桌面 QGIS 中，独立脚本里没有这个对象。
- 确认文件路径真实存在、编码与分隔符（CSV 等）正确；GeoPackage 矢量 URI 形如 路径|layername=图层名，提供者用 ogr。
- 文件型矢量（Shapefile、GPKG 矢量等）提供者一般是 ogr，栅格文件提供者是 gdal；不要把磁盘文件误写成 memory。
- PostGIS 提供者名是 postgres（需编译时带 Postgres 支持）；分隔文本是 delimitedtext 且 URI 以 file:// 开头；GPX 需带 ?type=track（或 route/waypoint）。
- 打不开某栅格格式时，先确认本机 GDAL 构建是否支持该格式，再查 URI（例如 GPKG 栅格常用 GPKG: 路径 : 图层名）。
- 加载后立刻打印 layer.isValid() 与错误摘要；独立进程还要确认已正确 initQgis()，否则投影与提供者常会“莫名”缺失。
控制台里菜单路径为 Plugins ► Python Console；启动时会执行 from qgis.core import * 与 import qgis.utils，并提供 iface（QgisInterface）访问画布与界面。更细的初始化与独立应用写法可对照官方 PyQGIS Developer Cookbook 介绍页（注意文档版本可能与本机安装不一致，以你安装的 API 为准）。
独立脚本：前缀路径与 init 顺序
独立脚本或无界面应用要先告诉 QGIS 装在哪，再初始化，最后业务代码，退出时清理。标准顺序如下。
- QgsApplication.setPrefixPath(“/path/to/qgis/installation”, True)（第二个参数 True 表示使用默认路径）。
- qgs = QgsApplication([], False)（不要 GUI 时用 False；自定义带界面应用改为 True）。
- qgs.initQgis() → 写业务逻辑（读图层、处理、写结果）。
- qgs.exitQgis()。
未 setPrefixPath 或未 initQgis 就加载图层，常见表现是提供者找不到、图层无效。命令行也可用 qgis –code qgis_init.py 在组件加载后执行脚本；–py-args 与可选的 — 之间的参数只进 Python 的 sys.argv。需要完整命令行参数时用 QgsApplication.instance().arguments()。用户目录下的 startup.py（Linux 常见为 .local/share/QGIS/QGIS3，Windows 为 AppData\Roaming\QGIS\QGIS3，macOS 为 Library/Application Support/QGIS/QGIS3）会在解释器初始化后较早执行，适合放全局补丁，但不要在里面做过重的阻塞逻辑。
- 部署可要求用户先装 QGIS，或把 QGIS 与应用一起打包；Linux 常交给包管理器，Windows/macOS 更常打包。
- 从源码编当前 master 时，官方 INSTALL 要求包括 CMake ≥ 3.22.0、Python ≥ 3.11、Qt ≥ 6.6.0，以及与 Qt 匹配的 PyQt、SIP 等；这是编译依赖，不等于安装包自带解释器版本说明，以你实际安装包为准。
版本与 API：QGIS 3、4 与 Qt6 迁移
QGIS 3 的 PyQGIS 绑定依赖 SIP 与 PyQt5；QGIS 4.0 于 2026-03-06 发布，迁到仅 Qt6，底层有 API 中断，官方尽量保留已弃用 API 以降低插件迁移成本，但表面“能打开”不等于旧脚本零改动。路线图说明源代码发布日后，各平台二进制通常数日内由维护者提供。2026-10-03 官方说明 4.x 仍有问题，不再把 QGIS 4.2 标为 LTR；当时预期后续 LTR 相关安排以官方公告为准。写脚本前先确认本机是 3.44.x LTR 还是 4.2.x 最新线，再查对应 PyQGIS API，避免把 PyQt5 写法直接拷到 PyQt6 环境。
- 同一台机器多版本并存时，PYTHONPATH / PATH 指向的必须与正在测的那个前缀路径一致。
- 插件迁移优先对照官方 Qt6 兼容说明与更新日志，分批替换已弃用符号。
- 不确定的符号与类名，以本机安装对应的 API 文档为准，不要只靠记忆里的 3.x 示例。
常见问题
为什么控制台里能跑，独立脚本就 ImportError？
控制台已经处在 QGIS 配好的 Python 与库环境中；独立进程默认没有这些路径。按上文设置 PYTHONPATH 与库搜索路径，并完成 setPrefixPath 与 initQgis 后再导入、加载图层。
图层对象不是 None，为什么地图上还是没有？
很多情况下返回的是无效图层实例，必须看 isValid()。同时检查提供者名、URI（尤其 GPKG 的 layername、CSV 的 file://）、以及独立进程是否已初始化提供者。
iface 报未定义或没有 addVectorLayer？
iface 属于桌面会话。独立脚本应使用 QgsVectorLayer / 工程与画布 API，不要依赖 iface；若在插件中使用，确认插件是在 QGIS 内加载的。
升级到 QGIS 4 后旧插件大量报错怎么办？
先确认是否仍在用 PyQt5 专用写法，再对照 4.x 变更与弃用 API 做迁移；短期可继续用 3.44 LTR 稳住生产脚本，同时在测试机验证 4.2.x。版本与是否 LTR 以官网版本文件和路线图为准。
排查 PyQGIS 报错时，先固定运行环境（控制台还是独立进程、3.44 还是 4.x），再查路径与库、初始化顺序、数据源 URI 与提供者，最后才怀疑业务逻辑。建议：每加载一层都断言 isValid()（或对 iface.add* 判断非空），并把本机 prefixPath、QGIS 版本号写进脚本头部注释，避免换机器后重复踩坑。