项目地址: https://github.com/qgis/QGIS
文档地址: https://github.com/qgis/QGIS-Documentation
在线文档: https://docs.qgis.org/4.2/en/docs/user_manual/processing/standalone.html
最新版本: QGIS 4.2.3;3.44 LTR 最新 3.44.15(截至 2026-10,GitHub Releases;
qgis_process自 QGIS 3.16 起可用)许可证: GPL-2.0+
概述
qgis_process 是 QGIS 自带的命令行工具(QGIS Processing Executor),允许在不启动 QGIS 桌面应用的情况下,直接从命令行运行 Processing 算法和模型(内置算法或由插件提供)。它适用于服务器端批量处理、CI/CD 自动化流水线、脚本化 GIS 工作流等场景。
源码位置:src/process/ 目录下的 main.cpp、qgsprocess.cpp、qgsprocess.h。
环境准备
前置条件
- 安装 QGIS 3.16+(
qgis_process从 QGIS 3.16 开始可用) - 确保
qgis_process可执行文件在PATH中
安装方式
# Ubuntu/Debian
sudo apt install qgis
# Conda(跨平台)
conda install -c conda-forge qgis
# Docker(官方镜像,含 qgis_process;stable=4.2、ltr=3.44)
docker run --rm -v "$PWD:/data" qgis/qgis:ltr qgis_process --version
# Windows:通过 OSGeo4W 安装器安装 QGIS,随后在 "OSGeo4W Shell" 中运行 qgis_process
提示: Windows 下手动运行的场景,将 QGIS 安装目录的
bin(如C:\Program Files\QGIS 3.44\bin或C:\OSGeo4W\bin)加入PATH。
无窗口系统(Headless 服务器)
在没有窗口管理器的系统上运行前,需设置环境变量:
export QT_QPA_PLATFORM=offscreen
验证安装
qgis_process --version
命令行语法
qgis_process [--help] [--version] [--json] [--verbose] [--no-python] [--skip-loading-plugins] [command] [algorithm id | model path | script path] [parameters]
全局选项
| 选项 | 说明 |
|---|---|
--help 或 -h |
输出帮助信息 |
--version 或 -v |
输出 QGIS Process 相关的所有版本信息 |
--json |
以 JSON 格式输出结果(AI/脚本友好) |
--verbose |
输出详细日志 |
--no-python |
禁用 Python 支持(启动更快) |
--skip-loading-plugins |
跳过加载已启用的插件(启动更快) |
可用命令
| 命令 | 说明 |
|---|---|
plugins |
列出可用和已激活的插件 |
plugins enable <name> |
启用已安装的插件 |
plugins disable <name> |
禁用已安装的插件 |
list |
列出所有可用的 Processing 算法 |
help <algorithm_id> |
显示指定算法的帮助信息 |
run <algorithm_id> [-- PARAM=VALUE ...] |
运行指定算法 |
注意: 只有在
metadata.txt中声明了hasProcessingProvider=yes的已安装插件才能被qgis_process识别和加载。
核心用法
1. 列出所有算法
qgis_process list
输出所有已注册 Provider 及其提供的算法 ID。
2. 查看算法帮助
qgis_process help qgis:regularpoints
输出算法的描述、参数列表(名称、类型、默认值、是否可选)和输出定义。
JSON 格式帮助(推荐 AI 使用)
qgis_process help native:buffer --json
JSON 输出结构:
{
"qgis_version": "...",
"algorithm_details": {
"id": "native:buffer",
"name": "Buffer",
"tags": ["..."]
},
"provider_details": {
"id": "native",
"name": "QGIS (native c++)"
},
"parameters": {
"INPUT": {
"name": "INPUT",
"description": "Input layer",
"type": {
"id": "source",
"name": "Vector Features",
"acceptable_values": ["Path to a vector layer"]
},
"optional": false,
"default_value": null
},
"DISTANCE": {
"name": "DISTANCE",
"description": "Distance",
"type": {
"id": "distance",
"name": "Distance"
},
"optional": false,
"default_value": 10
},
"OUTPUT": {
"name": "OUTPUT",
"description": "Buffered",
"type": {
"id": "sink",
"name": "Vector Layer Destination"
},
"is_destination": true,
"optional": false
}
},
"outputs": {
"OUTPUT": {
"description": "Buffered",
"type": "outputVector"
}
}
}
3. 运行算法
基本语法
qgis_process run <algorithm_id> -- PARAM1=VALUE1 PARAM2=VALUE2 ...
示例:缓冲区分析
qgis_process run native:buffer -- INPUT=source.shp DISTANCE=2 OUTPUT=buffered.shp
示例:合并图层(多值参数)
同一参数多次指定即可传入列表值:
qgis_process run native:mergevectorlayers -- LAYERS=input1.shp LAYERS=input2.shp OUTPUT=merged.shp
run 命令附加选项
| 选项 | 说明 |
|---|---|
--json |
以 JSON 格式输出执行结果 |
--ellipsoid=<name> |
指定椭球体,用于距离和面积计算 |
--distance_units=<unit> |
指定距离单位 |
--area_units=<unit> |
指定面积单位 |
--project_path=<path> |
加载已有 QGIS 项目文件供算法执行时使用 |
JSON 格式运行结果
qgis_process run native:buffer --json -- INPUT=source.shp DISTANCE=2 OUTPUT=buffered.shp
JSON 输出结构:
{
"qgis_version": "...",
"algorithm_details": { "id": "native:buffer" },
"inputs": {
"INPUT": "source.shp",
"DISTANCE": "2",
"OUTPUT": "buffered.shp"
},
"results": {
"OUTPUT": "/full/path/to/buffered.shp"
},
"log": ["..."]
}
4. 通过 STDIN 传入 JSON 参数(复杂参数)
当参数本身是复杂对象(如字典类型)时,可通过 STDIN 传入 JSON:
qgis_process run <algorithm_id> -
末尾的 - 表示从 STDIN 读取参数。JSON 必须包含 "inputs" 键:
echo '{"inputs": {"INPUT": "my_shape.shp", "DISTANCE": 5}}' | qgis_process run native:buffer -
完整 JSON 结构(含可选配置):
{
"ellipsoid": "EPSG:7019",
"distance_units": "feet",
"area_units": "ha",
"project_path": "/path/to/project.qgs",
"inputs": {
"INPUT": "my_shape.shp",
"DISTANCE": 5,
"SEGMENTS": 8,
"OUTPUT": "output.shp"
}
}
注意: 通过 STDIN 传入 JSON 时,输出自动使用 JSON 格式。
5. 插件管理
# 列出插件
qgis_process plugins
# 启用插件
qgis_process plugins enable cartography_tools
# 禁用插件
qgis_process plugins disable cartography_tools
6. 运行模型文件
qgis_process run /path/to/my_model.model3 -- INPUT=data.shp OUTPUT=result.shp
7. 运行 Python 脚本
qgis_process run /path/to/my_script.py -- INPUT=data.shp OUTPUT=result.shp
常用内置算法速查与参数类型参考见 reference/algorithm-cheatsheet.md
典型工作流
目标:把 data/points.shp 做 50 m 缓冲区写入 GeoPackage,并在 CI 中批量重复同一流程。
1. 先用 help 确认参数,不要凭记忆
qgis_process help native:buffer --json > buffer-help.json
读取 parameters 中 INPUT / DISTANCE / SEGMENTS / OUTPUT 的名称与类型;DISTANCE 是 distance 类型,单位取图层 CRS 单位(投影坐标系下即米,地理坐标系下是度,极易算错)。
2. 运行算法写出 GPKG
qgis_process run native:buffer --json -- \
INPUT=data/points.shp \
DISTANCE=50 \
SEGMENTS=8 \
DISSOLVE=false \
OUTPUT=out/points_buffer_50m.gpkg
results.OUTPUT 是实际写出的绝对路径,用它决定后续校验对象,不要自己拼路径。
3. 校验产物
ogrinfo -so out/points_buffer_50m.gpkg points_buffer_50m
核对要素数、CRS、几何类型;GPKG 内图层名默认取输出文件名(去扩展名)。log 里出现 returned non-zero 时即使进程退出码为 0 也算失败。
4. 批量循环(CI 脚本)
mkdir -p out
for f in data/*.shp; do
base=$(basename "$f" .shp)
qgis_process run native:buffer --json -- \
INPUT="$f" DISTANCE=50 OUTPUT="out/${base}_buffer.gpkg" \
|| { echo "FAILED: $f" >&2; exit 1; }
done
每次 run 都会新起一个 QGIS 进程(数秒开销);文件量大时改用 PyQGIS 的 processing.run() 在单进程内循环,见 ../pyqgis/SKILL.md。
输入 data/points.shp → native:buffer → out/points_buffer_50m.gpkg → ogrinfo 校验,构成 qgis_process 批处理的最小闭环。
常见问题
| 问题 | 解决方案 |
|---|---|
提示 command not found: qgis_process |
将 QGIS 的 bin 目录加入 PATH;Windows 下改用 OSGeo4W Shell 运行 |
| 无显示器的服务器上崩溃或卡住 | 设置环境变量 QT_QPA_PLATFORM=offscreen |
Algorithm <id> not found! |
用 qgis_process list 确认算法 ID 与 Provider 前缀(如 native:、gdal:) |
| 缺少必填参数 | 先用 qgis_process help <id> --json 查看参数名、类型与默认值 |
| 枚举参数报错 | 枚举值需传数字索引,help --json 中的 available_options 提供索引映射 |
| 多值参数只生效一项 | 在 -- 之后多次指定同一参数(如 LAYERS=a.shp LAYERS=b.shp) |
| 路径含空格或中文时报错 | 使用绝对路径并对参数值加引号 |
| 启动速度慢 | 不需要 Python/插件时添加 --no-python 与 --skip-loading-plugins |
| 模型/脚本或算法不可用 | 报 File <path> is not a valid Processing model! / ... is not a valid Processing script! / not available for use outside of the QGIS desktop application 时,改用 QGIS 桌面或 PyQGIS 脚本 |
算法 Provider 分类
| Provider ID | 说明 | 来源 |
|---|---|---|
native |
QGIS 原生 C++ 算法 | QGIS 内置 |
qgis |
QGIS Python 算法 | QGIS 内置 |
gdal |
GDAL/OGR 工具封装 | QGIS 内置 |
grass |
GRASS GIS 算法 | QGIS 内置(需 GRASS 安装) |
saga |
SAGA GIS 算法 | 插件提供 |
pdal |
点云处理算法 | QGIS 内置(需 PDAL) |
3d |
3D 分析算法 | QGIS 内置 |
| 其他 | 第三方插件 Provider | 各插件提供 |
AI 使用建议
- 本技能的组织:主文件给高频用法,完整参数表与高级示例在
reference/algorithm-cheatsheet.md,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。 - 执行环境:命令在终端 / shell 中执行(Windows 用 PowerShell)。Windows 下
qgis_process在C:\Program Files\QGIS 4.2\bin(LTR 为C:\Program Files\QGIS 3.44\bin)或 OSGeo4W Shell 里;PowerShell 设$env:QT_QPA_PLATFORM = "offscreen",不要照抄export。 - 先探测版本:
qgis_process --version(QGIS 4.2.3 或 LTR 3.44.15)、qgis_process list;低于 3.16 没有qgis_process,只能改用 PyQGIS 脚本;--no-python、--skip-loading-plugins可显著加快启动。 - 验证产物:
run ... --json里的results.OUTPUT是实际写出的绝对路径,再用ogrinfo -so(矢量)或gdalinfo -json(栅格)核对要素数、CRS、范围;日志中出现returned non-zero说明算法内部失败,不要只看进程退出码。 - 参数约定:
--之后的参数不带前导--;枚举传数字索引(help --json里的available_options是映射表);多值参数重复同一键(LAYERS=a.shp LAYERS=b.shp);路径含空格或中文时加引号,尽量用绝对路径。 - 常见报错:
Algorithm <id> not found!先查 provider 前缀(native:、gdal:、grass:),The following mandatory parameters were not specified回看help --json,requires a QGIS project to execute补--project_path。 - 安全与权限:
OUTPUT=指向已有文件会被覆盖;--project_path会加载项目内的数据源与凭证,注意不要把含密码的项目传给外部环境;启动 Docker 或安装 QGIS 前先征得用户同意,长任务放后台运行。
相关技能
- pyqgis — QGIS Python 绑定:../pyqgis/SKILL.md
- gdal — 命令行数据处理:../gdal/SKILL.md
- geopipe-agent — AI 原生分析流水线:../geopipe-agent/SKILL.md
- geoserver-rest-api — REST API 自动化:../geoserver-rest-api/SKILL.md
源码结构参考
源码位于 QGIS 仓库 src/process/ 目录:
| 文件 | 说明 |
|---|---|
main.cpp |
程序入口 |
qgsprocess.h |
QgsProcessingExec 类定义,包含命令分发、插件加载、算法执行等 |
qgsprocess.cpp |
核心实现:showUsage()(帮助)、listAlgorithms()(列表)、showAlgorithmHelp()(算法帮助)、execute()(执行算法) |
CMakeLists.txt |
构建配置 |
核心类
QgsProcessingExec:命令行执行器,负责解析命令和参数、加载插件、执行算法ConsoleFeedback:继承自QgsProcessingFeedback,处理控制台输出和进度显示,支持文本和 JSON 两种输出模式QgsProcessingExec::Flags:执行标志(UseJson、SkipPython、SkipLoadingPlugins)
关键方法
| 方法 | 说明 |
|---|---|
run(args, logLevel, flags) |
主入口,解析命令行参数并分发到对应子命令 |
showUsage(appName) |
输出使用帮助 |
showVersionInformation() |
输出版本信息 |
listAlgorithms() |
列出所有 Provider 和算法 |
listPlugins(useJson, showLoaded) |
列出插件信息 |
enablePlugin(name, enabled) |
启用/禁用插件 |
showAlgorithmHelp(id) |
显示算法帮助(支持文本和 JSON 输出) |
execute(algId, parameters, ...) |
执行算法核心逻辑 |
loadPlugins() |
加载 Python 插件 |
参考资源
- QGIS 源码: https://github.com/qgis/QGIS
- qgis_process 用户手册: https://docs.qgis.org/4.2/en/docs/user_manual/processing/standalone.html
- Processing 算法参考: https://docs.qgis.org/4.2/en/docs/user_manual/processing_algs/
- QGIS 下载(LTR/稳定版): https://qgis.org/download/
- QGIS 文档仓库: https://github.com/qgis/QGIS-Documentation
- 中文教程(znlgis): https://znlgis.github.io/gis/tutorial/qgis/