pyqgis

name	pyqgis
description	Use when extending QGIS with Python plugins, automating map composition, or scripting QGIS processing algorithms. PyQGIS: QGIS Python API for custom tools, processing scripts, and plugin development.
tags	["python","qgis","gis","processing","vector","raster","rendering","plugin"]

项目地址： https://github.com/qgis/QGIS

开发者手册： https://docs.qgis.org/3.44/en/docs/pyqgis_developer_cookbook/

Python API 参考： https://qgis.org/pyqgis/3.44/

许可证： GPL-2.0+

概述

PyQGIS 是 QGIS 桌面 GIS 软件的 Python 绑定层，对应 QGIS 源码中 python/ 目录下的绑定代码。它将 QGIS 核心 C++ 类库完整暴露给 Python，使得开发者可以：

• 在 QGIS Python 控制台中交互式操作
• 编写 独立 Python 脚本（无需启动 QGIS 桌面）
• 开发 QGIS 插件扩展桌面功能
• 调用 Processing 框架执行 100+ 种空间分析算法
• 进行 地图渲染与导出（PNG / PDF / SVG）

PyQGIS 主要包含以下模块：

模块	说明
qgis.core	核心类——图层、要素、几何、坐标系、项目、Processing 等
qgis.gui	GUI 组件——地图画布、地图工具、符号选择器等
qgis.analysis	空间分析——插值、网络分析、栅格计算等
qgis.processing	Processing 算法调用入口（processing.run()）
qgis.server	QGIS Server Python 插件接口
qgis.3d	3D 地图视图相关类
qgis.PyQt	PyQt5/PyQt6 兼容层

---

环境准备

前置条件

• 安装 QGIS 3.16+（查看 QGIS LTR/最新版）
• Python 3.9+（QGIS 自带 Python 环境）

在 QGIS Python 控制台中使用

打开 QGIS 桌面 → 菜单「Plugins → Python Console」，即可直接使用 PyQGIS：

# QGIS 控制台中无需初始化，直接使用
layer = iface.activeLayer()
print(layer.name(), layer.featureCount())

独立脚本（Standalone Script）

在 QGIS 外部运行 Python 脚本时，需要先初始化 QGIS 应用：

import sys
from qgis.core import QgsApplication

# 初始化 QGIS（False 表示不使用 GUI）
qgs = QgsApplication([], False)
qgs.setPrefixPath("/usr", True)  # Linux; Windows 示例："C:/OSGeo4W/apps/qgis"
qgs.initQgis()

# ===== 在此处编写 PyQGIS 代码 =====

# 退出
qgs.exitQgis()

独立脚本中使用 Processing

import sys
from qgis.core import QgsApplication
import processing
from processing.core.Processing import Processing

qgs = QgsApplication([], False)
qgs.setPrefixPath("/usr", True)
qgs.initQgis()

# 初始化 Processing 框架
Processing.initialize()

# 现在可以使用 processing.run()
result = processing.run("native:buffer", {
    'INPUT': '/data/points.shp',
    'DISTANCE': 100,
    'OUTPUT': '/data/buffered.shp'
})

qgs.exitQgis()

Headless 服务器环境

export QT_QPA_PLATFORM=offscreen
python3 my_pyqgis_script.py

---

核心类一览

项目与应用

类	模块	用途
QgsApplication	qgis.core	QGIS 应用实例，初始化/退出
QgsProject	qgis.core	项目管理（单例），加载/保存项目、管理图层

矢量图层与要素

类	模块	用途
QgsVectorLayer	qgis.core	矢量图层（Shapefile、GeoJSON、PostGIS、内存等）
QgsFeature	qgis.core	单个要素（几何 + 属性）
QgsField / QgsFields	qgis.core	属性字段定义与集合
QgsFeatureRequest	qgis.core	要素查询过滤器（空间/属性条件）
QgsVectorFileWriter	qgis.core	矢量数据写出（SHP、GPKG、GeoJSON 等）
QgsVectorLayerUtils	qgis.core	矢量图层工具方法集
QgsSpatialIndex	qgis.core	空间索引，加速空间查询

栅格图层

类	模块	用途
QgsRasterLayer	qgis.core	栅格图层（GeoTIFF、VRT、WMS 等）
QgsRasterPipe	qgis.core	栅格渲染管线
QgsRasterFileWriter	qgis.core	栅格数据写出

几何

类	模块	用途
QgsGeometry	qgis.core	几何对象封装（含空间操作方法）
QgsPointXY	qgis.core	二维点坐标
QgsPoint	qgis.core	三维点坐标（含 Z / M）
QgsRectangle	qgis.core	矩形范围（Bounding Box）
QgsWkbTypes	qgis.core	WKB 几何类型枚举
QgsDistanceArea	qgis.core	距离和面积计算（支持椭球面）

坐标参考系与变换

类	模块	用途
QgsCoordinateReferenceSystem	qgis.core	坐标参考系（CRS）对象
QgsCoordinateTransform	qgis.core	坐标变换器
QgsCoordinateTransformContext	qgis.core	坐标变换上下文

表达式

类	模块	用途
QgsExpression	qgis.core	QGIS 表达式解析与求值
QgsExpressionContext	qgis.core	表达式计算上下文
QgsExpressionContextUtils	qgis.core	创建预设表达式上下文的工具方法

Processing 框架

类	模块	用途
processing.run()	qgis.processing	执行 Processing 算法的核心入口
QgsProcessingFeedback	qgis.core	算法执行反馈（进度、日志）
QgsProcessingContext	qgis.core	算法执行上下文
QgsProcessingAlgorithm	qgis.core	自定义算法基类
QgsProcessingParameterDefinition	qgis.core	算法参数定义基类

地图渲染

类	模块	用途
QgsMapSettings	qgis.core	地图渲染设置（范围、CRS、图层、尺寸）
QgsMapRendererSequentialJob	qgis.core	顺序渲染任务
QgsMapRendererParallelJob	qgis.core	并行渲染任务
QgsLayoutExporter	qgis.core	打印布局导出（PDF、PNG、SVG）
QgsPrintLayout	qgis.core	打印布局对象

数据提供者

Provider 名称	说明	示例 URI
ogr	OGR 矢量（SHP、GeoJSON、GPKG、FileGDB 等）	/path/to/file.shp
gdal	GDAL 栅格（GeoTIFF、VRT、ECW 等）	/path/to/dem.tif
postgres	PostgreSQL / PostGIS	dbname='gis' host=localhost port=5432 table="public"."layer" (geom)
memory	内存图层	Point?crs=epsg:4326&field=id:integer&field=name:string(50)
wms	WMS / WMTS 服务	url=https://example.com/wms&layers=dem&crs=EPSG:4326
wfs	WFS 服务	url=https://example.com/wfs&typename=buildings
delimitedtext	CSV / 分隔文本	file:///path/to/data.csv?delimiter=,&xField=lon&yField=lat&crs=epsg:4326
spatialite	SpatiaLite 数据库	dbname='/path/to/db.sqlite' table="layer" (geometry)
virtual	虚拟图层（SQL 查询）	SQL 表达式

---

项目管理

加载与保存项目

from qgis.core import QgsProject

project = QgsProject.instance()

# 读取项目
project.read("/path/to/project.qgs")

# 获取所有图层
layers = project.mapLayers()  # 返回 dict {layer_id: layer}

# 保存项目
project.write("/path/to/output.qgs")

添加/移除图层

from qgis.core import QgsProject, QgsVectorLayer

project = QgsProject.instance()

layer = QgsVectorLayer("/data/roads.shp", "roads", "ogr")
if layer.isValid():
    project.addMapLayer(layer)

# 移除图层
project.removeMapLayer(layer.id())

---

矢量图层操作

加载矢量图层

from qgis.core import QgsVectorLayer

# 从文件加载
layer = QgsVectorLayer("/data/buildings.shp", "buildings", "ogr")

# 从 GeoPackage 加载指定图层
layer = QgsVectorLayer("/data/data.gpkg|layername=rivers", "rivers", "ogr")

# 从 PostGIS 加载
uri = 'dbname=\'gis\' host=localhost port=5432 user=\'postgres\' table="public"."parcels" (geom)'
layer = QgsVectorLayer(uri, "parcels", "postgres")

# 内存图层
layer = QgsVectorLayer("Point?crs=epsg:4326&field=id:integer&field=name:string(50)", "temp", "memory")

# 验证
if not layer.isValid():
    print("图层加载失败！")

遍历要素

for feature in layer.getFeatures():
    geom = feature.geometry()
    attrs = feature.attributes()
    print(feature.id(), geom.asWkt(), attrs)

按条件查询要素

from qgis.core import QgsFeatureRequest

# 按属性过滤
request = QgsFeatureRequest().setFilterExpression('"population" > 10000')
for feature in layer.getFeatures(request):
    print(feature["name"], feature["population"])

# 按空间范围过滤
from qgis.core import QgsRectangle
rect = QgsRectangle(116.0, 39.0, 117.0, 40.0)
request = QgsFeatureRequest().setFilterRect(rect)
for feature in layer.getFeatures(request):
    print(feature.id())

# 限制返回字段（提升性能）
request = QgsFeatureRequest().setSubsetOfAttributes(["name", "area"], layer.fields())

编辑要素

from qgis.core import QgsFeature, QgsGeometry, QgsPointXY

# 开启编辑
layer.startEditing()

# 添加要素
feat = QgsFeature(layer.fields())
feat.setGeometry(QgsGeometry.fromPointXY(QgsPointXY(116.4, 39.9)))
feat.setAttributes([1, "北京"])
layer.addFeature(feat)

# 修改已有要素属性
layer.changeAttributeValue(feature_id, field_index, new_value)

# 修改几何
layer.changeGeometry(feature_id, new_geometry)

# 删除要素
layer.deleteFeature(feature_id)

# 提交修改
layer.commitChanges()
# 或回滚
# layer.rollBack()

创建矢量文件

from qgis.core import (
    QgsVectorFileWriter, QgsVectorLayer, QgsFeature,
    QgsGeometry, QgsPointXY, QgsField, QgsFields,
    QgsCoordinateReferenceSystem, QgsWkbTypes
)
from qgis.PyQt.QtCore import QVariant

# 定义字段
fields = QgsFields()
fields.append(QgsField("id", QVariant.Int))
fields.append(QgsField("name", QVariant.String))

# 创建写入器
crs = QgsCoordinateReferenceSystem("EPSG:4326")
writer = QgsVectorFileWriter(
    "/data/output.shp",
    "UTF-8",
    fields,
    QgsWkbTypes.Point,
    crs,
    "ESRI Shapefile"
)

# 写入要素
feat = QgsFeature()
feat.setGeometry(QgsGeometry.fromPointXY(QgsPointXY(116.4, 39.9)))
feat.setAttributes([1, "北京"])
writer.addFeature(feat)

del writer  # 关闭文件

使用 SaveVectorOptions 写出（推荐）

from qgis.core import QgsVectorFileWriter

options = QgsVectorFileWriter.SaveVectorOptions()
options.driverName = "GPKG"
options.fileEncoding = "UTF-8"

error = QgsVectorFileWriter.writeAsVectorFormatV3(
    layer,
    "/data/output.gpkg",
    QgsProject.instance().transformContext(),
    options
)

空间索引

from qgis.core import QgsSpatialIndex

# 构建索引
index = QgsSpatialIndex(layer.getFeatures())

# 最近邻查询（返回要素 ID 列表）
nearest_ids = index.nearestNeighbor(QgsPointXY(116.4, 39.9), 5)

# 矩形范围查询
ids_in_rect = index.intersects(QgsRectangle(116.0, 39.0, 117.0, 40.0))

---

栅格图层操作

加载栅格图层

from qgis.core import QgsRasterLayer

# 从文件加载
layer = QgsRasterLayer("/data/dem.tif", "DEM")

# WMS 服务
uri = "url=https://example.com/wms&layers=elevation&crs=EPSG:4326&format=image/png"
layer = QgsRasterLayer(uri, "WMS Layer", "wms")

if not layer.isValid():
    print("栅格加载失败！")

查询栅格值

from qgis.core import QgsPointXY, QgsRaster

# 在指定坐标获取栅格值
point = QgsPointXY(116.4, 39.9)
result = layer.dataProvider().identify(point, QgsRaster.IdentifyFormatValue)
if result.isValid():
    values = result.results()  # {band_number: value}
    print(values)

栅格统计

from qgis.core import QgsRasterBandStats

stats = layer.dataProvider().bandStatistics(1, QgsRasterBandStats.All)
print(f"最小值: {stats.minimumValue}")
print(f"最大值: {stats.maximumValue}")
print(f"平均值: {stats.mean}")
print(f"标准差: {stats.stdDev}")

---

几何操作

创建几何

from qgis.core import QgsGeometry, QgsPointXY, QgsPoint

# 点
geom_pt = QgsGeometry.fromPointXY(QgsPointXY(116.4, 39.9))

# 折线
geom_line = QgsGeometry.fromPolylineXY([
    QgsPointXY(0, 0), QgsPointXY(10, 10), QgsPointXY(20, 0)
])

# 面
geom_poly = QgsGeometry.fromPolygonXY([[
    QgsPointXY(0, 0), QgsPointXY(10, 0),
    QgsPointXY(10, 10), QgsPointXY(0, 10),
    QgsPointXY(0, 0)
]])

# 从 WKT 创建
geom = QgsGeometry.fromWkt("POINT(116.4 39.9)")

# 从 WKB 创建
geom = QgsGeometry()
geom.fromWkb(wkb_bytes)

# 从 GeoJSON 创建（通过 QgsJsonUtils）
from qgis.core import QgsJsonUtils
features = QgsJsonUtils.stringToFeatureList(geojson_string)
if features:
    geom = features[0].geometry()

格式导出

wkt = geom.asWkt()        # WKT 字符串
wkb = geom.asWkb()        # WKB bytes
json_str = geom.asJson()  # GeoJSON 字符串

空间运算

# 缓冲区
buffered = geom.buffer(100, 16)

# 交集
intersection = geom1.intersection(geom2)

# 合并
union = geom1.combine(geom2)

# 差集
difference = geom1.difference(geom2)

# 对称差
sym_diff = geom1.symDifference(geom2)

# 凸包
hull = geom.convexHull()

# 质心
centroid = geom.centroid()

# 包围盒
bbox = geom.boundingBox()  # 返回 QgsRectangle

# 简化
simplified = geom.simplify(tolerance)

# 有效性检查
is_valid = geom.isGeosValid()

空间关系判断

geom1.intersects(geom2)   # 是否相交
geom1.contains(geom2)     # 是否包含
geom1.within(geom2)       # 是否在内部
geom1.overlaps(geom2)     # 是否重叠
geom1.touches(geom2)      # 是否相切
geom1.crosses(geom2)      # 是否交叉
geom1.disjoint(geom2)     # 是否不相交
geom1.equals(geom2)       # 是否相等

距离与面积计算

# 平面距离
dist = geom1.distance(geom2)

# 椭球面距离和面积（精确计算）
from qgis.core import QgsDistanceArea, QgsCoordinateReferenceSystem

da = QgsDistanceArea()
da.setSourceCrs(QgsCoordinateReferenceSystem("EPSG:4326"),
                QgsProject.instance().transformContext())
da.setEllipsoid("WGS84")

length = da.measureLength(line_geom)
area = da.measureArea(polygon_geom)

# 两点间大地测量距离
d = da.measureLine(QgsPointXY(116.4, 39.9), QgsPointXY(121.5, 31.2))

---

坐标参考系与变换

创建 CRS

from qgis.core import QgsCoordinateReferenceSystem

# 从 EPSG 代码
crs = QgsCoordinateReferenceSystem("EPSG:4326")

# 从 WKT
crs = QgsCoordinateReferenceSystem.fromWkt(wkt_string)

# 从 Proj 字符串
crs = QgsCoordinateReferenceSystem.fromProj4(proj4_string)

# 获取图层 CRS
crs = layer.crs()
print(crs.authid())       # "EPSG:4326"
print(crs.description())  # "WGS 84"

坐标变换

from qgis.core import QgsCoordinateTransform, QgsCoordinateReferenceSystem, QgsProject

src_crs = QgsCoordinateReferenceSystem("EPSG:4326")
dst_crs = QgsCoordinateReferenceSystem("EPSG:3857")

transform = QgsCoordinateTransform(src_crs, dst_crs, QgsProject.instance())

# 变换单个点
point = transform.transform(QgsPointXY(116.4, 39.9))

# 变换几何
geom.transform(transform)

# 反向变换
point_back = transform.transform(point, QgsCoordinateTransform.ReverseTransform)

---

表达式

基本表达式求值

from qgis.core import QgsExpression, QgsExpressionContext, QgsExpressionContextUtils

# 简单计算
exp = QgsExpression("1 + 2 * 3")
result = exp.evaluate()  # 7

# 基于要素的表达式
exp = QgsExpression('"population" / "area"')
context = QgsExpressionContext()
context.appendScopes(QgsExpressionContextUtils.globalProjectLayerScopes(layer))

for feature in layer.getFeatures():
    context.setFeature(feature)
    value = exp.evaluate(context)
    print(feature["name"], value)

过滤要素

# 表达式过滤
exp = QgsExpression('"type" = \'residential\' AND "area" > 1000')
request = QgsFeatureRequest(exp)

for feature in layer.getFeatures(request):
    print(feature.attributes())

字段计算器

from qgis.core import QgsExpression

layer.startEditing()

# 使用表达式批量更新字段
expression = QgsExpression('"length" * "width"')
context = QgsExpressionContext()
context.appendScopes(QgsExpressionContextUtils.globalProjectLayerScopes(layer))

field_index = layer.fields().indexOf("area")
for feature in layer.getFeatures():
    context.setFeature(feature)
    value = expression.evaluate(context)
    layer.changeAttributeValue(feature.id(), field_index, value)

layer.commitChanges()

---

Processing 算法调用

基本调用

import processing

# 运行缓冲区分析
result = processing.run("native:buffer", {
    'INPUT': '/data/roads.shp',
    'DISTANCE': 50,
    'SEGMENTS': 10,
    'END_CAP_STYLE': 0,      # 0=圆形, 1=平头, 2=方形
    'JOIN_STYLE': 0,          # 0=圆形, 1=斜角, 2=斜切
    'MITER_LIMIT': 2,
    'DISSOLVE': False,
    'OUTPUT': '/data/roads_buffer.shp'
})
print(result['OUTPUT'])  # 输出文件路径

带反馈对象

from qgis.core import QgsProcessingFeedback

feedback = QgsProcessingFeedback()

result = processing.run("native:dissolve", {
    'INPUT': '/data/polygons.shp',
    'FIELD': ['type'],
    'OUTPUT': '/data/dissolved.gpkg'
}, feedback=feedback)

使用内存输出

# OUTPUT 设为 'memory:' 前缀可得到内存图层
result = processing.run("native:buffer", {
    'INPUT': layer,
    'DISTANCE': 100,
    'OUTPUT': 'memory:buffered'
})
buffered_layer = result['OUTPUT']  # QgsVectorLayer（内存）

图层对象作为输入

# 可以直接传入 QgsVectorLayer / QgsRasterLayer 对象
result = processing.run("native:clip", {
    'INPUT': input_layer,       # QgsVectorLayer 对象
    'OVERLAY': clip_layer,      # QgsVectorLayer 对象
    'OUTPUT': 'memory:clipped'
})

常用 Processing 算法

算法 ID	说明	关键参数
native:buffer	缓冲区	INPUT, DISTANCE, SEGMENTS, DISSOLVE
native:clip	矢量裁剪	INPUT, OVERLAY
native:dissolve	融合	INPUT, FIELD
native:intersection	交集	INPUT, OVERLAY
native:union	联合	INPUT, OVERLAY
native:difference	差集	INPUT, OVERLAY
native:centroids	质心	INPUT
native:reprojectlayer	重投影	INPUT, TARGET_CRS
native:mergevectorlayers	合并图层	LAYERS
native:fixgeometries	修复几何	INPUT
native:extractbyattribute	按属性提取	INPUT, FIELD, OPERATOR, VALUE
native:extractbylocation	按位置提取	INPUT, INTERSECT, PREDICATE
native:joinattributesbylocation	空间连接	INPUT, JOIN, PREDICATE, METHOD
native:fieldcalculator	字段计算器	INPUT, FIELD_NAME, FORMULA
gdal:cliprasterbyextent	栅格按范围裁剪	INPUT, EXTENT
gdal:cliprasterbymask	栅格按掩膜裁剪	INPUT, MASK
gdal:warpreproject	栅格重投影	INPUT, TARGET_CRS
gdal:merge	栅格合并	INPUT
gdal:contour	等值线提取	INPUT, INTERVAL
gdal:polygonize	栅格转矢量	INPUT
gdal:rasterize	矢量转栅格	INPUT, FIELD

查询可用算法

# 在 QGIS 控制台中列出所有算法
for alg in QgsApplication.processingRegistry().algorithms():
    print(alg.id(), "-", alg.displayName())

# 搜索算法
for alg in QgsApplication.processingRegistry().algorithms():
    if 'buffer' in alg.id().lower():
        print(alg.id(), alg.displayName())

---

地图渲染与导出

渲染为图片

from qgis.core import QgsMapSettings, QgsMapRendererSequentialJob
from qgis.PyQt.QtCore import QSize

settings = QgsMapSettings()
settings.setLayers([layer])
settings.setDestinationCrs(layer.crs())
settings.setExtent(layer.extent())
settings.setOutputSize(QSize(1920, 1080))

job = QgsMapRendererSequentialJob(settings)
job.start()
job.waitForFinished()

image = job.renderedImage()
image.save("/data/map_output.png")

使用打印布局导出 PDF

from qgis.core import (
    QgsProject, QgsPrintLayout, QgsLayoutItemMap,
    QgsLayoutExporter, QgsLayoutSize, QgsUnitTypes
)

project = QgsProject.instance()
layout = QgsPrintLayout(project)
layout.initializeDefaults()

# 添加地图项
map_item = QgsLayoutItemMap(layout)
map_item.setRect(20, 20, 200, 150)
map_item.setExtent(layer.extent())
map_item.setLayers([layer])
layout.addLayoutItem(map_item)

# 导出 PDF
exporter = QgsLayoutExporter(layout)
pdf_settings = QgsLayoutExporter.PdfExportSettings()
exporter.exportToPdf("/data/output.pdf", pdf_settings)

---

典型工作流示例

示例 1：矢量格式转换（SHP → GeoPackage）

from qgis.core import QgsVectorLayer, QgsVectorFileWriter, QgsProject

layer = QgsVectorLayer("/data/input.shp", "input", "ogr")

options = QgsVectorFileWriter.SaveVectorOptions()
options.driverName = "GPKG"
options.fileEncoding = "UTF-8"

QgsVectorFileWriter.writeAsVectorFormatV3(
    layer,
    "/data/output.gpkg",
    QgsProject.instance().transformContext(),
    options
)

示例 2：批量缓冲区 + 融合

import processing

# 缓冲区
result1 = processing.run("native:buffer", {
    'INPUT': '/data/points.shp',
    'DISTANCE': 500,
    'SEGMENTS': 16,
    'OUTPUT': 'memory:buffered'
})

# 融合
result2 = processing.run("native:dissolve", {
    'INPUT': result1['OUTPUT'],
    'OUTPUT': '/data/dissolved.gpkg'
})

示例 3：坐标系转换 + 属性过滤

import processing

# 重投影到 CGCS2000
result1 = processing.run("native:reprojectlayer", {
    'INPUT': '/data/input_wgs84.shp',
    'TARGET_CRS': 'EPSG:4490',
    'OUTPUT': 'memory:reprojected'
})

# 按属性提取
result2 = processing.run("native:extractbyattribute", {
    'INPUT': result1['OUTPUT'],
    'FIELD': 'type',
    'OPERATOR': 0,  # 0=等于
    'VALUE': 'road',
    'OUTPUT': '/data/roads_cgcs2000.gpkg'
})

示例 4：栅格裁剪 + 坡度分析

import processing

# 按掩膜裁剪 DEM（栅格算法使用 TEMPORARY_OUTPUT 生成临时文件）
result1 = processing.run("gdal:cliprasterbymask", {
    'INPUT': '/data/dem.tif',
    'MASK': '/data/boundary.shp',
    'OUTPUT': 'TEMPORARY_OUTPUT'  # 栅格输出不支持 memory:，使用 TEMPORARY_OUTPUT 创建临时文件
})

# 坡度分析
result2 = processing.run("gdal:slope", {
    'INPUT': result1['OUTPUT'],
    'OUTPUT': '/data/slope.tif'
})

示例 5：从 CSV 创建矢量图层并导出

from qgis.core import QgsVectorLayer, QgsVectorFileWriter, QgsProject

# 从 CSV 加载（指定经纬度字段）
uri = "file:///data/stations.csv?delimiter=,&xField=longitude&yField=latitude&crs=epsg:4326"
layer = QgsVectorLayer(uri, "stations", "delimitedtext")

if layer.isValid():
    options = QgsVectorFileWriter.SaveVectorOptions()
    options.driverName = "GeoJSON"
    QgsVectorFileWriter.writeAsVectorFormatV3(
        layer,
        "/data/stations.geojson",
        QgsProject.instance().transformContext(),
        options
    )

示例 6：独立脚本完整示例

"""独立 PyQGIS 脚本：加载 SHP、缓冲区分析、导出 GeoJSON"""
import sys
from qgis.core import (
    QgsApplication, QgsVectorLayer, QgsProject
)
import processing
from processing.core.Processing import Processing

# 初始化
qgs = QgsApplication([], False)
qgs.setPrefixPath("/usr", True)
qgs.initQgis()
Processing.initialize()

# 加载数据
layer = QgsVectorLayer("/data/buildings.shp", "buildings", "ogr")
assert layer.isValid(), "图层加载失败"

# 缓冲区分析
result = processing.run("native:buffer", {
    'INPUT': layer,
    'DISTANCE': 200,
    'OUTPUT': '/data/buildings_buffer.geojson'
})

print(f"输出文件: {result['OUTPUT']}")

# 退出
qgs.exitQgis()

---

AI 使用建议

推荐工作流

1. 初始化环境：独立脚本需 QgsApplication 初始化；QGIS 控制台中可直接使用
2. 加载数据：使用 QgsVectorLayer / QgsRasterLayer 加载数据源
3. 执行分析：优先使用 processing.run() 调用算法（参数统一、算法丰富）；精细操作使用 QgsGeometry 方法
4. 导出结果：使用 QgsVectorFileWriter 写出矢量，QgsRasterFileWriter 写出栅格
5. 清理退出：独立脚本调用 qgs.exitQgis()

关键注意事项

1. 始终检查图层有效性：加载图层后必须检查 layer.isValid()，无效时检查路径和 Provider。
2. 坐标系一致性：空间运算前确保所有图层使用相同 CRS；使用 native:reprojectlayer 或 QgsCoordinateTransform 进行转换。
3. 编辑模式：修改图层数据需 startEditing() → 操作 → commitChanges()；失败可 rollBack()。
4. Processing 内存输出：将 OUTPUT 设为 'memory:name' 可得到内存图层，避免创建临时文件。
5. 椭球面计算：对地理坐标（经纬度）计算距离/面积时，使用 QgsDistanceArea 并设置椭球体，或使用 Processing 算法指定椭球体。
6. Headless 环境：无显示器的服务器上必须设置 QT_QPA_PLATFORM=offscreen。
7. 文件路径使用绝对路径：避免工作目录不确定导致文件找不到。
8. 大数据量优化：使用 QgsSpatialIndex 加速空间查询；使用 QgsFeatureRequest 限制返回字段和范围。
9. 表达式语法：字段名用双引号 "field"，字符串值用单引号 'value'。
10. QGIS 版本兼容：部分 API 在不同版本间有变化，建议使用 LTR 版本（查看当前 LTR）以获得稳定接口；QGIS 4.2.0 已于 2026-07 发布为稳定版，3.44 LTR 仍受支持。

错误处理

# 图层加载失败
layer = QgsVectorLayer(path, name, provider)
if not layer.isValid():
    print(f"图层加载失败: {layer.error().message()}")

# Processing 算法错误
try:
    result = processing.run("native:buffer", params, feedback=feedback)
except Exception as e:
    print(f"算法执行失败: {e}")

# 编辑提交失败
if not layer.commitChanges():
    errors = layer.commitErrors()
    print(f"提交失败: {errors}")
    layer.rollBack()

---

相关技能

• qgis-process — QGIS 命令行处理工具：../qgis-process/SKILL.md
• gdal — 命令行数据处理：../gdal/SKILL.md
• geopandas — Python 矢量数据处理：../geopandas/SKILL.md
• shapely — Python 几何计算核心：../shapely/SKILL.md
• geopipe-agent — AI 原生分析流水线：../geopipe-agent/SKILL.md

参考链接

• QGIS 源码仓库： https://github.com/qgis/QGIS
• PyQGIS 开发者手册（3.44）： https://docs.qgis.org/3.44/en/docs/pyqgis_developer_cookbook/
• PyQGIS API 参考（3.44）： https://qgis.org/pyqgis/3.44/
• QGIS 文档仓库： https://github.com/qgis/QGIS-Documentation
• QGIS 用户手册： https://docs.qgis.org/3.44/en/docs/user_manual/
• PyQGIS 速查表： https://docs.qgis.org/3.44/en/docs/pyqgis_developer_cookbook/cheat_sheet.html