QGis开发环境部署

想要搭建完整的 QGIS 开发环境，核心是实现 "能编译 QGIS 源码 + 能基于 QGIS 做二次开发（插件 / 独立应用）"，我会分 Windows（最常用） 和 Linux（开发 / 生产） 两个系统，以 Qt 6.6.1 + QGIS 3.34（LTS，稳定支持 Qt 6）为例，给出一步到位的部署方案，新手也能跟着操作。

一、核心前提

QGIS 3.34 是首个支持 Qt 6 的 LTS 版本，适配 Qt 6.4+（推荐 6.6.1）；
开发环境核心依赖：Qt（含开发套件）+ QGIS（源码 / 开发包）+ 基础编译工具 + GIS 依赖库（GDAL/PROJ 等）；
优先选择 "官方预编译开发包"（无需手动编译 GDAL 等），降低复杂度。

二、Windows 系统（Qt 6.6.1 + QGIS 3.34）

步骤 1：安装基础工具

表格

工具	版本要求	下载地址	安装要点
Visual Studio	2022（带 C++ 开发组件）	https://visualstudio.microsoft.com/zh-hans/downloads/	勾选 "桌面应用 C++ 开发"+"Windows SDK"
CMake	3.24+	https://cmake.org/download/	安装时勾选 "Add CMake to system PATH"
Git	最新版	https://git-scm.com/download/win	勾选 "Git Bash Here"，方便后续克隆源码

步骤 2：安装 Qt 6.6.1（含兼容模块）

下载 Qt 维护工具（Qt Online Installer）：https://www.qt.io/download-open-source
运行安装器，登录 Qt 账号（免费开源版即可）；
选择 "Custom installation"，找到 Qt 6.6.1 → 勾选：
- MSVC 2019 64bit（匹配 VS 2022，兼容）；
- Qt 5 Compatibility Module（必须，对应 qt6Core5Compat.dll）；
- Qt Creator（IDE，推荐 12.0+）；
安装路径建议：C:\Qt\6.6.1（避免中文 / 空格）。

步骤 3：安装 QGIS 开发包（无需编译源码）

新手优先用官方预编译的 QGIS 开发包，省去编译 GDAL/PROJ 的麻烦：

下载 QGIS 3.34 OSGeo4W 安装包：https://download.osgeo.org/osgeo4w/osgeo4w-setup-x86_64.exe
运行安装包，选择 "Advanced Install"→"Next"；
选择 "Install from Internet"，安装路径建议：C:\OSGeo4W；
在 "Select Packages" 中，搜索并勾选：
- qgis-dev（QGIS 开发库 + 头文件）；
- qgis（QGIS 主程序，可选，用于测试）；
- gdal-dev、proj-dev（GIS 依赖库开发包）；
等待安装完成（约 2-3GB），安装后目录结构：
- 头文件：C:\OSGeo4W\apps\qgis\include；
- 库文件：C:\OSGeo4W\apps\qgis\lib；
- 运行库：C:\OSGeo4W\apps\qgis\bin。

步骤 4：配置 Qt Creator 开发环境

打开 Qt Creator 12.0+，进入 "工具 → 选项 → 构建和运行 → 编译器"：
- 确认已识别 VS 2022 的 MSVC 64bit 编译器；
进入 "工具链"，添加 CMake 路径（C:\Program Files\CMake\bin\cmake.exe）；
配置 QGIS 依赖（以新建 QGIS 插件项目为例）：新建 Qt Widgets 项目，修改 .pro 文件（关键）：

Qt 6 核心模块（含兼容模块）

QT += core gui widgets network sql svg core5compat

QGIS 头文件路径

INCLUDEPATH += C:/OSGeo4W/apps/qgis/include
INCLUDEPATH += C:/OSGeo4W/include # GDAL/PROJ 头文件

QGIS 库路径（链接核心/界面库）

LIBS += -LC:/OSGeo4W/apps/qgis/lib -lqgis_core -lqgis_gui -lqgis_app

运行时依赖：添加 OSGeo4W 库路径

DESTDIR = $$PWD/bin # 输出目录
QMAKE_POST_LINK += copy /Y C:\OSGeo4W\apps\qgis\bin\* $$DESTDIR\

步骤 5：测试开发环境

新建简单测试代码（显示 QGIS 地图画布）：

复制代码

#include <QApplication>
#include <QMainWindow>
// QGIS 头文件
#include <qgis/core/QgsApplication>
#include <qgis/gui/QgsMapCanvas>

int main(int argc, char *argv[])
{
    // 1. 初始化 QGIS 应用（必须在 QApplication 之前）
    QgsApplication qgisApp(argc, argv, true);
    // 设置 QGIS 资源路径（OSGeo4W 安装路径）
    qgisApp.setPrefixPath("C:/OSGeo4W/apps/qgis", true);
    qgisApp.initQgis();

    // 2. 创建 Qt 主窗口和 QGIS 地图画布
    QMainWindow window;
    QgsMapCanvas *canvas = new QgsMapCanvas(&window);
    window.setCentralWidget(canvas);
    window.resize(800, 600);
    window.setWindowTitle("QGIS 开发环境测试");
    window.show();

    // 3. 运行应用
    int ret = qgisApp.exec();

    // 4. 清理 QGIS 资源
    qgisApp.exitQgis();
    return ret;
}

编译运行：若弹出包含空白地图画布的窗口，说明环境配置成功；
常见问题：若提示 DLL 缺失，将 C:\OSGeo4W\apps\qgis\bin 和 C:\Qt\6.6.1\msvc2019_64\bin 加入系统环境变量 PATH。

三、Linux 系统（Ubuntu 22.04 + Qt 6.6.1 + QGIS 3.34）

步骤 1：安装系统依赖

复制代码

# 更新源
sudo apt update && sudo apt upgrade -y

# 安装基础编译工具
sudo apt install -y build-essential cmake git libssl-dev

# 安装 GIS 依赖库（GDAL/PROJ/GEOS）
sudo apt install -y libgdal-dev libproj-dev libgeos-dev libsqlite3-dev

# 安装 Qt 6 依赖
sudo apt install -y libqt6core5compat6-dev libqt6widgets6-dev libqt6svg6-dev

步骤 2：安装 Qt 6.6.1

下载 Qt Online Installer：https://www.qt.io/download-open-source

赋予执行权限并运行：

复制代码

chmod +x qt-unified-linux-x64-online.run
./qt-unified-linux-x64-online.run

选择 Qt 6.6.1 → 勾选 GCC 64bit + Qt 5 Compatibility Module + Qt Creator，安装路径：/opt/Qt/6.6.1。

步骤 3：安装 QGIS 开发包

复制代码

# 添加 QGIS 官方源
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt update

# 安装 QGIS 开发包
sudo apt install -y qgis-dev qgis

头文件路径：/usr/include/qgis；
库文件路径：/usr/lib/x86_64-linux-gnu。

步骤 4：配置 Qt Creator

打开 Qt Creator，进入 "工具 → 选项 → 构建和运行"：
- 确认识别 GCC 编译器和 CMake；

新建项目，修改 CMakeLists.txt（Linux 推荐 CMake）：

复制代码

cmake_minimum_required(VERSION 3.24)
project(QGIS_Demo)

# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 查找 Qt 6 模块
find_package(Qt6 REQUIRED COMPONENTS Core Widgets Core5Compat)

# 查找 QGIS 模块
find_package(QGIS REQUIRED COMPONENTS Core Gui)

# 添加可执行文件
add_executable(QGIS_Demo main.cpp)

# 链接库
target_link_libraries(QGIS_Demo PRIVATE
    Qt6::Core
    Qt6::Widgets
    Qt6::Core5Compat
    QGIS::Core
    QGIS::Gui
)

步骤 5：测试环境

运行和 Windows 相同的测试代码，编译后执行：

复制代码

./QGIS_Demo

若弹出地图画布窗口，说明环境配置成功。

四、常见问题与解决方案

QGIS 头文件找不到 ：
- 检查头文件路径是否正确（Windows：C:\OSGeo4W\apps\qgis\include；Linux：/usr/include/qgis）；
- 确认安装了 qgis-dev 开发包（而非仅 qgis 运行包）。
链接时提示 "找不到 qgis_core" ：
- 检查库路径是否正确，且库文件存在（如 qgis_core.lib/libqgis_core.so）；
- Linux 需运行 sudo ldconfig 更新库缓存。
运行时缺失 qt6Core5Compat.dll ：
- 确认 Qt 安装时勾选了 Qt 5 Compatibility Module；
- 将该 DLL 复制到程序运行目录（Windows）或 /usr/lib（Linux）。
QGIS 初始化失败 ：
- 确保 setPrefixPath 指向 QGIS 安装路径（如 C:\OSGeo4W\apps\qgis）；
- 检查 initQgis() 调用在 QApplication::exec() 之前。

总结

Windows 环境优先用 OSGeo4W 安装 QGIS 开发包，无需手动编译 GIS 依赖，搭配 Qt 6.6.1 需勾选兼容模块；
Linux 环境通过官方源安装 qgis-dev，配置 CMake 链接 Qt 6 和 QGIS 库即可；
核心验证方式：编译运行包含 QgsMapCanvas 的测试程序，能弹出地图画布即配置成功。

QGis开发环境部署

一、核心前提

二、Windows 系统（Qt 6.6.1 + QGIS 3.34）

步骤 1：安装基础工具

步骤 2：安装 Qt 6.6.1（含兼容模块）

步骤 3：安装 QGIS 开发包（无需编译源码）

步骤 4：配置 Qt Creator 开发环境

Qt 6 核心模块（含兼容模块）

QGIS 头文件路径

QGIS 库路径（链接核心/界面库）

运行时依赖：添加 OSGeo4W 库路径

步骤 5：测试开发环境

三、Linux 系统（Ubuntu 22.04 + Qt 6.6.1 + QGIS 3.34）

步骤 1：安装系统依赖

步骤 2：安装 Qt 6.6.1

步骤 3：安装 QGIS 开发包

步骤 4：配置 Qt Creator

步骤 5：测试环境

四、常见问题与解决方案

总结