QGIS Python怎么入门?控制台代码咋写?

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

很多刚接触二次开发的同学会问：QGIS Python怎么入门?控制台代码咋写? 如果你已经会打开 QGIS、加载矢量或栅格数据，但不知道 Python 控制台里第一行代码该怎么写，这篇文章就按“能马上操作”的方式，带你从 QGIS Python 控制台入门到写出几段常用 GIS 自动化代码。

引言：先把 QGIS Python 控制台当成“可交互的 GIS 命令行”

QGIS Python 入门不一定要从插件开发开始。对初学者来说，更稳妥的路线是先学会在 Python 控制台 里读取当前工程、获取图层、遍历要素、修改字段、调用处理工具。

这样做有两个好处：

• 不用先搭建复杂开发环境，打开 QGIS 就能练习。
• 每一行代码都能马上看到地图或属性表变化，适合理解 PyQGIS 的对象模型。
• 以后写批处理脚本、模型工具、插件代码时，很多语法都可以直接复用。

本文默认你使用的是 QGIS 3.x 版本。QGIS 3 使用的是 Python 3，核心接口通常称为 PyQGIS，也就是 QGIS 暴露给 Python 的 API。

背景：为什么很多人卡在 QGIS Python 入门第一步

初学 QGIS Python 经常遇到的不是语法问题，而是“不知道对象从哪里来”。例如：

• 当前工程怎么获取？
• 图层面板里的图层怎么用代码拿到？
• 属性表里的字段和要素怎么读取？
• 为什么有些代码复制进去能运行，有些提示对象不存在？
• 控制台代码和独立 Python 脚本有什么区别？

QGIS Python 控制台的特点是：它运行在 QGIS 内部，因此可以直接访问当前打开的工程、地图画布、图层面板和处理工具。这一点和普通的系统 Python 解释器不同。

如果你在 Windows 的命令行、Anaconda、VS Code 普通 Python 环境里直接写：

from qgis.core import QgsProject

很可能会报错，因为普通 Python 环境并没有自动配置 QGIS 的运行库。而在 QGIS 自带的 Python 控制台中，这些对象通常已经可用。

原理：QGIS Python 控制台代码到底在操作什么

理解 QGIS Python 入门，建议先记住 4 个常用对象：

对象	常见写法	作用
当前工程	QgsProject.instance()	获取当前打开的 QGIS 工程，管理图层、坐标系、工程路径等
图层	iface.activeLayer()	获取当前在图层面板中选中的图层
要素	layer.getFeatures()	遍历矢量图层中的空间对象和属性记录
处理工具	processing.run()	调用缓冲区、裁剪、叠加、栅格处理等算法

其中 iface 是 QGIS Python 控制台里非常重要的对象，全称可以理解为 QGIS 用户界面接口。它能帮你访问当前选中图层、地图画布、图层树等界面元素。

而 QgsProject.instance() 代表当前 QGIS 工程。你在图层面板中看到的多数图层，都可以从这个工程对象里获取。

步骤：QGIS Python 控制台代码从哪里开始写

步骤 1：打开 QGIS Python 控制台

1. 启动 QGIS。
2. 打开一个已有工程，或者先加载一个矢量数据，例如 Shapefile、GeoPackage、GeoJSON。
3. 点击菜单 插件。
4. 选择 Python 控制台。
5. 在控制台底部输入代码，按回车执行。

建议初学时先加载一个面数据或点数据图层，并在图层面板中选中它。后面的示例会使用当前选中图层。

步骤 2：获取当前选中图层

在 QGIS Python 控制台输入：

layer = iface.activeLayer()
print(layer.name())

如果控制台输出了图层名称，说明你已经成功用代码拿到了当前图层。

为了避免空对象错误，可以写得更稳一点：

layer = iface.activeLayer()

if layer is None:
    print("请先在图层面板中选中一个图层")
else:
    print("当前图层：", layer.name())

这是 QGIS Python 控制台代码里最常见的起步写法。很多错误都是因为没有选中图层，导致 layer 是 None。

步骤 3：查看图层基本信息

拿到图层后，可以查看几项常用信息：

layer = iface.activeLayer()

print("图层名称：", layer.name())
print("要素数量：", layer.featureCount())
print("几何类型：", layer.geometryType())
print("坐标系：", layer.crs().authid())

这里的 featureCount() 返回要素数量，crs().authid() 返回坐标参考系统编号，例如 EPSG:4326 或 EPSG:3857。

如果你正在排查面积不准、距离不准、叠加错位等问题，先用这段代码检查坐标系非常有用。

步骤 4：读取字段名称

属性表中的字段可以这样读取：

layer = iface.activeLayer()

for field in layer.fields():
    print(field.name(), field.typeName())

输出结果会显示字段名和字段类型。写 QGIS Python 控制台代码时，字段名必须和属性表中完全一致，包括大小写、下划线和中文字符。

步骤 5：遍历要素并读取属性

假设你的图层中有一个字段叫 name，可以这样读取每个要素的名称：

layer = iface.activeLayer()

for feature in layer.getFeatures():
    print(feature["name"])

如果字段不存在，会报错。更稳妥的写法是先判断字段是否存在：

layer = iface.activeLayer()
field_name = "name"

field_names = [field.name() for field in layer.fields()]

if field_name not in field_names:
    print("字段不存在：", field_name)
else:
    for feature in layer.getFeatures():
        print(feature[field_name])

这类写法适合入门阶段反复练习，因为它能帮助你理解“图层、字段、要素、属性值”之间的关系。

步骤 6：读取几何面积或长度

对于面图层，可以读取几何面积：

layer = iface.activeLayer()

for feature in layer.getFeatures():
    geom = feature.geometry()
    print(geom.area())

对于线图层，可以读取长度：

layer = iface.activeLayer()

for feature in layer.getFeatures():
    geom = feature.geometry()
    print(geom.length())

注意：这里得到的数值单位取决于图层坐标系。如果图层是经纬度坐标系，例如 EPSG:4326，面积和长度结果通常不适合直接当作平方米或米使用。实际项目中应先投影到合适的投影坐标系，再计算面积或长度。

步骤 7：选择符合条件的要素

假设字段 type 中有道路类型，可以选择所有 primary 类型的要素：

layer = iface.activeLayer()

ids = []

for feature in layer.getFeatures():
    if feature["type"] == "primary":
        ids.append(feature.id())

layer.selectByIds(ids)
print("已选择要素数量：", len(ids))

执行后，地图和属性表中符合条件的要素会被选中。这是 QGIS Python 控制台最直观的练习之一。

步骤 8：用表达式选择要素

QGIS 也支持用表达式选择要素。比如选择人口字段 population 大于 100000 的记录：

layer = iface.activeLayer()
layer.selectByExpression('"population" > 100000')

表达式中的字段名通常用双引号包起来，文本值用单引号包起来。例如：

layer = iface.activeLayer()
layer.selectByExpression('"city" = '杭州'')

这种方式适合从手工筛选过渡到自动化筛选。

步骤 9：新增字段并写入属性值

如果要给当前矢量图层新增一个字段，需要使用编辑模式。下面示例新增字段 area_m2，并写入几何面积：

from qgis.PyQt.QtCore import QVariant
from qgis.core import QgsField

layer = iface.activeLayer()

layer.startEditing()

layer.dataProvider().addAttributes([
    QgsField("area_m2", QVariant.Double)
])
layer.updateFields()

area_index = layer.fields().indexFromName("area_m2")

for feature in layer.getFeatures():
    geom = feature.geometry()
    area = geom.area()
    layer.changeAttributeValue(feature.id(), area_index, area)

layer.commitChanges()

print("面积字段写入完成")

这段代码是 QGIS Python 入门中非常实用的案例，但也要注意坐标系单位。如果图层不是投影坐标系，写入的面积值可能没有实际业务意义。

步骤 10：调用 QGIS 处理工具

QGIS 的很多工具都可以通过 processing.run() 调用。下面示例对当前图层做缓冲区，距离为 100，输出到临时图层：

import processing

layer = iface.activeLayer()

result = processing.run(
    "native:buffer",
    {
        "INPUT": layer,
        "DISTANCE": 100,
        "SEGMENTS": 8,
        "END_CAP_STYLE": 0,
        "JOIN_STYLE": 0,
        "MITER_LIMIT": 2,
        "DISSOLVE": False,
        "OUTPUT": "TEMPORARY_OUTPUT"
    }
)

buffer_layer = result["OUTPUT"]
QgsProject.instance().addMapLayer(buffer_layer)

print("缓冲区生成完成：", buffer_layer.name())

如果这段代码运行成功，你会在图层面板中看到一个新的缓冲区图层。学习 QGIS Python 控制台代码时，建议优先练习这些可视化结果明显的工具。

常见坑：QGIS Python 控制台代码为什么会报错

坑 1：没有选中图层

如果你运行：

layer = iface.activeLayer()
print(layer.name())

却提示类似 'NoneType' object has no attribute 'name'，通常是因为图层面板中没有选中任何图层。

解决办法：

• 先在图层面板点击一个图层。
• 再运行 layer = iface.activeLayer()。
• 养成判断 layer is None 的习惯。

坑 2：字段名写错

如果出现字段读取错误，优先打印字段列表：

layer = iface.activeLayer()

for field in layer.fields():
    print(field.name())

字段名中的中文、空格、大小写、下划线都要完全匹配。建议实际项目中尽量使用英文、数字和下划线命名字段。

坑 3：忘记进入编辑模式

修改属性或几何时，很多情况下需要：

layer.startEditing()

修改完成后还需要：

layer.commitChanges()

如果中途发现写错了，可以使用：

layer.rollBack()

入门阶段建议先在测试数据上练习，不要直接修改唯一的生产数据。

坑 4：面积和长度单位理解错

几何对象的 area() 和 length() 返回的是图层坐标单位下的结果。经纬度坐标系的单位是度，不是米。

如果要计算平方米或米，常见做法是：

• 先确认图层坐标系。
• 选择适合研究区的投影坐标系。
• 使用“另存为”或处理工具重投影图层。
• 再计算面积或长度。

坑 5：把控制台代码直接拿到外部 Python 运行

QGIS Python 控制台中的 iface 是 QGIS 界面提供的对象，普通 Python 环境里没有它。

如果你要写独立 PyQGIS 脚本，需要额外初始化 QGIS 应用环境。初学阶段不建议一开始就做独立脚本，先把控制台代码练熟更高效。

方法比较：控制台、脚本、模型构建器和插件该怎么选

方式	适合场景	优点	限制
QGIS Python 控制台	入门练习、快速测试、临时批处理	上手快，能直接操作当前工程	不适合长期维护复杂流程
QGIS 脚本工具	固定参数的批处理流程	可以复用，也能接入处理工具箱	需要更规范地管理输入输出
模型构建器	不想写太多代码的流程编排	可视化，适合串联多个处理工具	复杂逻辑和条件判断不如代码灵活
QGIS 插件	给团队或用户提供完整功能界面	交互友好，可发布和安装	学习成本更高，需要理解插件结构和界面开发

对大多数 GIS 初学者，推荐路线是：

1. 先用 QGIS Python 控制台练习对象和语法。
2. 再把常用代码整理成脚本。
3. 需要流程化时使用处理工具箱或模型构建器。
4. 确实要做工具产品时，再学习插件开发。

检查清单：写 QGIS Python 控制台代码前先确认这些

• 是否已经在 QGIS 中打开或加载数据？
• 是否在图层面板中选中了目标图层？
• 目标图层是矢量还是栅格？当前代码是否适用于该类型？
• 字段名是否与属性表完全一致？
• 是否需要进入编辑模式？
• 修改前是否备份了原始数据？
• 面积、长度计算是否使用了合适的投影坐标系？
• 输出结果是临时图层还是保存到文件？
• 代码是否对空图层、空选择、字段不存在做了判断？
• 如果调用处理工具，算法 ID 和参数名称是否正确？

FAQ：QGIS Python 入门常见问题

QGIS Python 怎么入门最合适？

建议从 QGIS Python 控制台开始，而不是直接写插件。先练习获取当前图层、读取字段、遍历要素、选择要素、修改属性、调用处理工具。掌握这些后，再学习脚本工具和插件开发会顺很多。

QGIS Python 控制台代码和普通 Python 代码一样吗？

语法都是 Python，但运行环境不同。QGIS Python 控制台运行在 QGIS 内部，可以直接使用 iface、当前工程和当前图层。普通 Python 环境不能直接使用这些对象，除非额外配置 PyQGIS 环境。

QGIS Python 控制台里怎么获取当前图层？

最常用写法是：

layer = iface.activeLayer()

如果没有选中图层，返回值可能是 None。实际代码中建议先判断：

if layer is None:
    print("请先选中图层")

QGIS Python 怎么遍历属性表？

可以使用 layer.getFeatures() 遍历要素，再用字段名读取属性：

layer = iface.activeLayer()

for feature in layer.getFeatures():
    print(feature["name"])

如果不确定字段名，先打印 layer.fields() 中的字段列表。

QGIS Python 可以批量处理数据吗？

可以。常见方式是使用 processing.run() 调用 QGIS 处理工具，例如缓冲区、裁剪、融合、重投影、字段计算等。入门阶段可以先在控制台中测试单个图层，确认参数正确后再扩展为批量循环。

为什么 QGIS Python 计算面积结果不对？

通常是坐标系问题。几何面积的单位取决于图层坐标系。如果图层是 EPSG:4326 这类经纬度坐标系，直接计算面积不会得到平方米。应先把数据投影到适合研究区的投影坐标系，再计算面积。

QGIS Python 入门需要安装额外的 Python 吗？

一般不需要。QGIS 自带 Python 环境和 Python 控制台。初学阶段直接使用 QGIS 内置环境即可。只有在写独立脚本、自动化服务或集成外部库时，才需要进一步配置环境。

结论：先会控制台，再谈脚本和插件

QGIS Python 入门的关键不是背 API，而是先建立清晰的操作链条：当前工程、当前图层、字段、要素、几何、处理工具。只要能在 QGIS Python 控制台里稳定写出获取图层、遍历要素、选择记录、修改字段和调用处理工具的代码，你就已经迈过了最重要的第一关。

后续如果要继续提升，可以把本文中的控制台代码整理成可复用脚本，再逐步学习处理工具箱脚本、模型构建器和 QGIS 插件开发。对 GIS 学生和初级工程师来说，这条路线比一开始就啃完整插件框架更实际，也更容易看到成果。