QGIS自定义Python插件开发步骤

Python
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

QGIS 自定义 Python 插件开发,官方推荐路径很清晰:先定目标,再搭目录结构,写代码与文档,可选做翻译,用重载方式反复测试,最后按规范打包发布。核心落地动作是:在用户插件目录建好含 metadata.txt 与 __init__.py(含 classFactory(iface))的文件夹,主类实现 initGui() 与 unload(),菜单/工具栏挂到 iface 上。本篇只讲这一章的开发步骤与验收要点;环境选型、Python/SIP 兼容与避坑见 QGIS插件开发环境配置与 Python、SIP 版本兼容说明,整体流程与环境难度另见 QGIS插件开发流程与环境配置说明。

QGIS 自定义 Python 插件开发七步流程示意

开发前先想清楚:目标与模板怎么选

动手前先确认要解决什么 GIS 问题(批处理图层、自定义工具栏、Processing 算法等),并在官方插件仓库搜一遍是否已有同类插件,避免重复造轮子。确定要做后,再选模板:教学或极简原型可用最小化模板;要菜单、对话框、本地化与测试骨架时,用 Plugin Builder——QGIS 3 对应 Plugin Builder 3,面向 QGIS 4 / Qt6 用 Plugin Builder 4。生成后的工程再按你的业务改,比从零建目录更稳。

开发机上建议同时准备:Qt Designer(画界面)、对应版本的 pyuic / pyrcc(或 Qt6 侧工具)、以及能把工程部署到插件目录的工具(如 pb_tool)。调试阶段强烈建议装 Plugin Reloader,改完代码一键重载,不必反复重启 QGIS。更完整的环境与调试路径可对照 QGIS插件开发流程与环境搭建要点。

  • 目标写清:输入图层/CRS、输出结果、是否进 Processing
  • 模板选型:极简模板 vs Plugin Builder 3/4
  • 工具链:Designer、资源编译、pb_tool、Plugin Reloader

插件目录与 metadata.txt 必须怎么写

插件最终是一个独立文件夹,复制到当前用户配置下的 python/plugins(也可用 QGIS_PLUGINPATH 追加路径)。Windows 常见位置是 %APPDATA%\QGIS\QGIS3\profiles\default\python\plugins,Linux / macOS 在对应用户配置目录;不确定时用 Settings → User Profiles → Open Active Profile Folder 打开确认。文件夹名只用 ASCII 字母、数字、下划线或连字符,且不能以数字开头——发布时这也是硬性规则。

典型 QGIS Python 插件目录结构示意

官方要求的典型结构如下(带“必需”的缺一不可):

  • metadata.txt(必需,UTF-8):描述插件身份与兼容版本
  • __init__.py(必需):提供 classFactory(iface)
  • 主逻辑文件(如 mainPlugin.py):实现插件类
  • form.ui / 编译后的界面模块(有自定义 GUI 时)
  • resources.qrc / 编译后的资源模块(可选)
  • LICENSE(发布到官方仓库必需,纯文本、无扩展名,需 GPL 兼容)

若是 Processing 插件,还要在 metadata 里写 hasProcessingProvider=yes,并增加 provider 与算法模块,在 initGui 中注册 QgsProcessingProvider。

字段 是否必需 说明
name / description / about / version 必需 名称、简介、详细说明、版本号;版本在仓库内须唯一
qgisMinimumVersion 必需 最低兼容版本,如 3.28 或 4.0
author / email / repository 必需 作者、联系邮箱、代码仓库地址
qgisMaximumVersion 可选 为空时上传官方仓库会自动设为 major.99;双版本兼容常显式写到 4.99
category / tags / icon / homepage / tracker 可选 菜单分类(Vector/Raster/Database/Web/Mesh 等)、标签、图标与链接
plugin_dependencies / experimental / deprecated 可选 依赖其他插件、实验标记、废弃标记

字段含义与发布约束以 QGIS PyQGIS 插件开发说明(官方 Cookbook) 为准;写完后用文本编辑器确认无 BOM、编码为 UTF-8。

核心代码:classFactory、initGui 与 unload 怎么实现

__init__.py 的职责很单一:被 QGIS 加载时调用 classFactory(iface),返回插件实例。常见写法是从同目录主模块导入类并构造,例如:

  1. 在 __init__.py 中定义 classFactory(iface),内部 from .mainPlugin import YourPlugin,再 return YourPlugin(iface)
  2. 主类 __init__(self, iface) 保存 iface 引用,初始化动作、对话框等成员
  3. 实现 initGui(self):创建 QAction,用 iface.addPluginToMenu / addToolBarIcon 挂菜单与工具栏;需要帮助入口可用 pluginHelpMenu()
  4. 实现 unload(self):对称地移除菜单、工具栏图标并断开信号,避免泄漏与重复挂载
  5. 业务逻辑放在槽函数里(打开对话框、读当前图层、写要素、调用 Processing 等),界面逻辑与 GIS 逻辑尽量分开

自定义界面时,用 Qt Designer 出 .ui,再编译成 Python 模块后在对话框中加载。资源(图标等)走 .qrc 编译。面向 QGIS 4(仅 Qt6)时,优先通过 qgis.PyQt 兼容层导入,不要写死 PyQt5/PyQt6;枚举要用完整路径(如 Qt.ItemDataRole.UserRole、QgsMapLayer.LayerType.VectorLayer)。旧的 supportsQt6 已废弃移除,不要再写。需要双版本时,metadata 里显式设置合适的 qgisMinimumVersion / qgisMaximumVersion(例如兼容到 4.99),并在 Qt6 环境用官方迁移脚本辅助改 API,改完务必实测。

怎么测试、重载与验收

开发阶段不要每次改完都重启 QGIS。把工程部署到插件目录(pb_tool 的 deploy,或手工复制),启用插件后用 Plugin Reloader 重载;也可在 Python 控制台执行 qgis.utils.reloadPlugin(‘你的插件目录名’)。UI/资源有改动时先重新编译再部署,否则界面仍是旧版。

建议按下面清单自测,通过再考虑发布:

  • 启用/禁用插件各一次:菜单与图标出现、消失正确,无报错
  • 在空工程、有矢量/栅格图层、不同 CRS 下各跑通主功能一次
  • 故意给错误输入(空选择、无效路径),确认提示可读且不崩
  • QGIS 3 LTR 与 QGIS 4 最新版各测一轮(截至 2026 年 11 月,常见二进制约有 LTR 3.44.x 与 4.2.x;具体以官网下载页为准)
  • 若声明了 Processing Provider:算法出现在工具箱,批处理与建模可用

打包前删掉生成物与无关文件(如误提交的 ui_*.py 中间文件、.gitignore、本地缓存)。zip 内必须是“单层插件目录”,不要多包一层杂目录。

发布到官方仓库时要注意什么

官方仓库地址为 plugins.qgis.org,需 OSGeo 账号。上传包须满足:独立目录名规则、含 metadata.txt、__init__.py、LICENSE、版本号唯一。建议附 README、图标,并填好 repository / tracker / homepage;名称里不要重复堆 “plugin”;标签与 category 选准,方便检索。上传后通常要审核(具备权限的用户可自动批准)。只在内网分发时,也可以自建简单 XML 插件仓库,步骤见官方 releasing 文档。

更多发布细则可核对 QGIS 插件发布与仓库要求(官方文档)。版本号与路线图以官网为准;截至 2026 年 11 月,QGIS 4.0 起为 Qt6 重大升级,后续点版本持续修复,生产环境选型时注意 LTR 与 Latest 的差异。

常见问题

改完代码插件行为不变怎么办?

多半是还在跑旧副本:确认部署目录就是当前 profile 下的 plugins,用 Plugin Reloader 或 reloadPlugin 重载;改过 .ui/.qrc 要先重新编译再部署。仍异常时禁用后重启 QGIS 再启用,排除残留引用。

QGIS 4 里插件不显示或不加载?

检查 metadata 的最小/最大版本是否覆盖当前主版本;去掉已废弃的 supportsQt6;把直接 PyQt5 调用改到 qgis.PyQt 与完整枚举路径,并用迁移说明做一轮对照测试。仅支持 QGIS 4 时可设 qgisMinimumVersion=4.0;要兼顾 3 与 4 则合理设置 max(如 4.99)并分环境验证。

官方仓库校验失败常见原因有哪些?

目录名含非 ASCII 或以数字开头、缺少 LICENSE、metadata 缺必需字段、版本号与已发布冲突、zip 结构多包一层或夹带了不应提交的生成文件。按官方 checklist 逐项改后再传。

普通插件和 Processing 插件差在哪?

Processing 插件需在 metadata 声明 hasProcessingProvider=yes,实现并注册 Provider 与算法类,让工具出现在处理工具箱;普通 GUI 插件侧重菜单/工具栏与对话框。两者可以并存于同一工程,但注册与卸载都要在 initGui/unload 里成对处理。

自定义 Python 插件开发,抓住“合规目录 + metadata/__init__ + initGui/unload + 重载测试 + 按规范打包”这条主线即可落地;Qt6 / QGIS 4 相关 API 与版本字段要提前规划,避免发版后才发现不加载。建议先用 Plugin Builder 生成骨架跑通一次启用/重载/卸载,再往主流程里加业务;环境与兼容细节不确定时,优先对照本站环境配置文与官方 Cookbook,在 LTR 与当前 Latest 各验收一遍再上传仓库。