qgis-process

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

文档地址： https://github.com/qgis/QGIS-Documentation

在线文档： https://docs.qgis.org/4.2/en/docs/user_manual/processing/standalone.html

许可证： 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 中

无窗口系统（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"
    }
  }
}