如何搭建基于OSGeo4W/QGIS的C++开发环境？

一、前置准备 #

• 安装带开发组件的QGIS：Windows安装时勾选Developer Tools组件，Linux直接装qgis-devel或libqgis-dev包。必须保证QGIS版本和后续用的Qt版本匹配（QGIS 3.x对应Qt 5.x，QGIS 4.x对应Qt 6.x）。
• 安装对应版本的Qt：Qt版本要和QGIS依赖的完全一致，比如QGIS 3.34用Qt 5.15.2，就别装Qt 6。同时选对编译器套件（比如QGIS用MSVC 2019，就装Qt的MSVC 2019套件）。
• 配置环境变量：Windows把QGIS的bin、lib路径，还有Qt的bin路径加到系统PATH；Linux确保LD_LIBRARY_PATH包含QGIS库路径，避免运行时找不到库。

二、Qt Creator配置步骤 #

1. 新建Qt Widgets项目，选和QGIS、Qt匹配的编译器。
2. 修改项目的.pro文件，添加QGIS的头文件和库链接：

   # Windows示例路径，换成你实际的QGIS安装路径
   INCLUDEPATH += "C:/Program Files/QGIS 3.34/include/qgis"
   LIBS += -L"C:/Program Files/QGIS 3.34/lib" -lqgis_core -lqgis_gui
   
   # Linux示例路径
   # INCLUDEPATH += /usr/include/qgis
   # LIBS += -L/usr/lib -lqgis_core -lqgis_gui
   

3. 检查项目设置：确认编译器和Qt套件和QGIS兼容，别选错版本。

三、Visual Studio配置步骤 #

1. 先装Qt VS Tools插件，然后新建Qt Widgets项目。
2. 打开项目属性面板：
   • C/C++ -> 常规 -> 附加包含目录：添加QGIS的include路径（比如C:\Program Files\QGIS 3.34\include\qgis）。
   • 链接器 -> 常规 -> 附加库目录：添加QGIS的lib路径（比如C:\Program Files\QGIS 3.34\lib）。
   • 链接器 -> 输入 -> 附加依赖项：加上qgis_core.lib、qgis_gui.lib（Debug版本用带_d后缀的库，比如qgis_core_d.lib）。
3. 通过Qt VS Tools选择和QGIS匹配的Qt版本，确保编译器（MSVC版本）和QGIS一致。

四、测试Map Canvas最简代码 #

在主窗口类里加个简单的Map Canvas实现，验证环境是否正常：

#include <QMainWindow>
#include <qgsmapcanvas.h>
#include <qgsvectorlayer.h>
#include <qgsproject.h>

class MainWindow : public QMainWindow
{
    Q_OBJECT

public:
    MainWindow(QWidget *parent = nullptr)
        : QMainWindow(parent)
    {
        // 必须先初始化QGIS
        QgsApplication::setPrefixPath("C:/Program Files/QGIS 3.34", true);
        QgsApplication::initQgis();

        // 创建Map Canvas并设为主窗口中心部件
        QgsMapCanvas *canvas = new QgsMapCanvas(this);
        setCentralWidget(canvas);

        // 添加一个测试内存图层
        QgsVectorLayer *testLayer = new QgsVectorLayer("point?crs=EPSG:4326", "Test Layer", "memory");
        if (testLayer->isValid()) {
            QgsProject::instance()->addMapLayer(testLayer);
            canvas->setLayers({testLayer});
            canvas->zoomToFullExtent();
        }
    }

    ~MainWindow()
    {
        // 退出时清理QGIS资源
        QgsApplication::exitQgis();
    }
};

Windows下要把QGIS的qgis_core.dll、qgis_gui.dll等复制到项目输出目录，或者靠环境变量让程序找到它们。

五、避坑要点 #

• 版本绝对要匹配：QGIS、Qt、编译器三者版本不匹配会直接导致链接错误或运行崩溃，比如QGIS用MSVC 2019，就别用MSVC 2022编译。
• QGIS初始化不能忘：所有QGIS API调用前必须先调用setPrefixPath和initQgis()，退出时一定要调用exitQgis()，不然会内存泄漏或崩溃。
• 打包依赖：Windows发布程序时，除了Qt的dll，还要把QGIS的核心、GUI库以及它们的依赖dll都打包进去，可以用windeployqt处理Qt部分，手动复制QGIS的库。

内容的提问来源于stack exchange，提问作者BHadh