1. 环境准备：安装QGIS和VS2017

搞GIS二次开发，第一步就是把环境搭好。我当初第一次配置的时候，光是找安装包就折腾了半天，后来才发现直接从官网下载最靠谱。这里分享下我的经验，帮你避开那些坑。

首先去QGIS官网下载OSGeo4W安装包。注意要选LTR（长期支持）版本，3.16ltr这个版本比较稳定，适合开发用。下载完成后直接运行osgeo4w-setup.exe，安装过程中有几个关键点要注意：

• 选择"Install from Internet"方式安装
• 安装路径最好不要有中文和空格，我习惯放在E:\OSGeo4W
• 下载缓存目录可以单独设置，比如E:\Temp
• 网络设置选"Use System Proxy Settings"
• 添加国内镜像源会快很多，比如http://gwmodel.whu.edu.cn/mirrors/osgeo4w

安装VS2017建议选专业版或企业版，社区版也行但功能会少一些。安装时要勾选"使用C++的桌面开发"工作负载，还有Windows 10 SDK。我第一次装的时候漏了SDK，结果编译各种报错，又得重新跑一遍安装程序。

2. 配置QGIS开发环境

装好基础软件后，接下来要配置开发环境。这一步最容易出问题，我遇到过好几次编译失败的情况。

首先在项目目录下创建thirdPart/qgis文件夹，把E:\OSGeo4W\apps\qgis-ltr下的include和lib目录拷贝过来。这里有个细节要注意：如果项目是32位的，得用32位的库文件；64位项目用64位的库。我曾经因为混用导致一堆链接错误。

然后在VS2017里配置项目属性：

1. 附加包含目录添加..\thirdPart\qgis\include
2. 附加库目录添加..\thirdPart\qgis\lib
3. 附加依赖项添加qgis_core.lib、qgis_app.lib、qgis_gui.lib
4. 预处理器定义添加_USE_MATH_DEFINES

配置Qt环境也很关键。在VS的扩展菜单里找到"Qt VS Tools"，设置Qt版本路径，比如E:\OSGeo4W\apps\Qt5。这一步如果没做对，后面编译会提示找不到Qt头文件。

3. 解决运行时的依赖问题

好不容易编译通过，运行又可能出问题。最常见的就是缺少DLL，我整理了一份必须拷贝的DLL清单：

1. QGIS核心DLL：E:\OSGeo4W\apps\qgis-ltr\bin下的所有DLL
2. GDAL相关：E:\OSGeo4W\apps\gdal-dev\bin
3. PROJ相关：E:\OSGeo4W\apps\proj-dev\bin
4. Qt插件：E:\OSGeo4W\apps\Qt5\plugins下的platforms和imageformats目录
5. QGIS插件：E:\OSGeo4W\apps\qgis-ltr\plugins
6. 投影数据：E:\OSGeo4W\share\proj

记得把这些都拷贝到你的exe所在目录。我第一次运行时界面出不来，就是因为漏了platforms插件。还有一次地图显示异常，发现是没拷贝proj的数据文件。

4. 编写第一个QGIS程序

环境搭好了，来写个简单的demo测试下。这个例子加载一个shp文件并显示：

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

int main(int argc, char *argv[])
{
    QgsApplication app(argc, argv, true);
    QgsApplication::initQgis();
    
    QgsMapCanvas canvas;
    QgsVectorLayer* layer = new QgsVectorLayer("E:/data/rivers.shp", "rivers", "ogr");
    if(!layer->isValid()) {
        qDebug() << "图层加载失败";
        return -1;
    }
    
    QgsProject::instance()->addMapLayer(layer);
    canvas.setExtent(layer->extent());
    canvas.setLayers({layer});
    canvas.show();
    
    return app.exec();
}

这个程序有几个注意点：

1. 必须调用initQgis()初始化QGIS环境
2. 图层路径要换成你自己的shp文件路径
3. 记得把图层添加到QgsProject管理
4. 最后一定要调用app.exec()启动事件循环

如果运行时提示找不到proj.db，可能是环境变量没设置好。可以手动设置PROJ_LIB环境变量指向E:\OSGeo4W\share\proj。

5. 调试技巧和常见问题

调试QGIS程序有些特殊技巧。比如在VS里调试时，可以在"调试"->"选项"里设置符号服务器，这样能调试到QGIS的源码。具体路径是：

SRV*E:\SymbolCache*https://msdl.microsoft.com/download/symbols

常见问题及解决方案：

1. 编译时报LNK2019链接错误：检查库路径是否正确，确保所有依赖库都添加了
2. 运行时崩溃：通常是DLL版本不匹配，建议全部用OSGeo4W里的DLL
3. 界面显示异常：检查是否拷贝了Qt的plugins目录
4. 投影显示不正确：确认proj数据文件已正确部署

我遇到过最头疼的问题是release和debug版本混用导致的崩溃。后来总结的经验是：要么全部用debug版本，要么全部用release版本，不要混着用。

6. 进阶开发建议

掌握了基础开发后，可以尝试更复杂的功能。QGIS提供了丰富的API，比如：

1. 地图工具：实现地图交互，如缩放、平移、测量等
2. 渲染器：自定义图层渲染方式
3. 数据处理：调用QGIS的空间分析算法
4. 插件开发：扩展QGIS功能

建议多看看官方API文档，里面有很多示例代码。开发复杂功能时，可以先在QGIS桌面版里测试效果，再用代码实现。比如要做一个缓冲区分析，可以先在QGIS里用工具菜单试试，确保参数设置正确，再调用对应的API。

调试时可以启用QGIS的日志输出，在代码里加：

QgsApplication::setLogLevel(QgsApplication::LogLevel::LogAll);

这样能在输出窗口看到详细的调试信息。