ARTICLE · 1294771
qgis插件开发入门
DeepGIS专注OpenGIS、AI、大数据、SD/HD数据等相关技术分享。 +关注不迷路
空间数据处理系列
本文目录
一、先装两样东西
二、用 Builder 生成第一个插件
三、生成的代码里，你该碰哪几处
四、改两行，让它真的干点活
五、装进 QGIS 跑起来
六、下一步往哪走
一、先装两样东西
QGIS 去官网下。长期支持版（LTR）和最新版界面不一样，但插件写法两边基本通用。
第二样是 Plugin Builder，QGIS 官方出的插件脚手架。打开「插件 → 管理和安装插件」搜它装上就行。
有一点要分清：QGIS 3 装 Plugin Builder 3，QGIS 4 装 Plugin Builder 4，两套不通用。
不用脚手架也能手写插件，但新手别跟自己过不去，生成骨架那一步把一堆重复活都干完了。
二、用 Builder 生成第一个插件
从「插件」菜单打开 Builder，向导就几步：
1. 填插件名，随便起，比如 My First Plugin； 2. 插件类型选 Tool button with dialog——工具栏多个按钮，点了弹对话框，最常见的那种； 3. 菜单挂哪儿选 Plugins 就行； 4. 后面一排复选框（翻译、帮助、测试、Makefile……），新手全勾上没坏处，用不上以后删。
点生成，问存哪就选个你找得到的目录。
生成出来文件不少，你真正要关心的就四个：
• __init__.py：入口，QGIS 靠它认你的插件；• my_plugin.py：主逻辑，活儿都在这儿干；• my_plugin_dialog.py和my_plugin_dialog_base.ui：那个对话框；• metadata.txt：插件名片，填基本信息。
剩下 Makefile、test、help、i18n 都是脚手架附带的，先别管。
三、生成的代码里，你该碰哪几处
主类在 my_plugin.py，骨架替你写好了 QGIS 必认的三个方法：
• initGui()：插件启用时调，往工具栏加按钮、往菜单加项；• unload()：插件禁用时调，把加进去的按钮菜单摘掉（不加这步，来回启用会在工具栏排出一串重复按钮）；• run()：点按钮时调，负责打开对话框。
你自己的功能就写在这三个方法里，最常见的写在 run() 或对话框的「确定」按钮回调里。
对话框长什么样由 .ui 文件决定，用 Qt Designer 拖控件。入门阶段先不碰它，咱们用最简单的方式先把插件跑通。
四、改两行，让它真的干点活
打开 my_plugin.py，找到 run()，在打开对话框那句后面加一行：
def run(self):
self.dlg.show()
# 下面这行是我们加的：在 QGIS 顶部消息栏弹一句话
self.iface.messageBar().pushMessage("第一个插件跑起来了")不用改 .ui，不用拖任何控件，保存就行。
这行的作用是：你点插件按钮之后，QGIS 顶部的消息栏会冒出一句"第一个插件跑起来了"。看到它，就说明你的插件链路通了。
想做更复杂的事——读当前图层、往地图加要素、弹个输入框——逻辑都写在 run() 或按钮回调里，原理一样。
五、装进 QGIS 跑起来
把整个插件目录丢进 QGIS 的插件文件夹：
• Windows： C:\Users\你\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\• macOS： ~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/• Linux： ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/
注意路径里的 QGIS3，QGIS 4 要换成 QGIS4，两代目录互不相干，丢错一边插件管理器里就是空的。
不想每次拷文件，设个环境变量 QGIS_PLUGINPATH 指向源码目录，QGIS 启动时会把它加进插件搜索路径，改完重启一次生效。
然后打开「插件 → 管理和安装插件 → 已安装」，找到你的插件勾上，重启 QGIS。工具栏上出现你的按钮，点一下，顶部消息栏那句话就出来了。
改完代码想看效果，装个 Plugin Reloader，点一下重载，不用重启。报错去「视图 → 面板 → 日志消息」里看，插件在那有自己的标签页。
六、下一步往哪走
第一个插件跑通，后面就是往 run() 里填你真正想要的功能。
想做带界面的，用 Qt Designer 改 .ui，生成的 .ui 和 .qrc 要编成 .py 才能用，Builder 配套的 pb_tool compile 一条命令搞定。想发布到官方插件库，配 qgis-plugin-ci 或者打个 zip 手动传都行。
这些留到进阶篇。先把第一个跑起来。
