写在前面：
本笔记根据多方资料整理而成，旨在为QGIS二次开发提供学习参考。内容仅供交流学习，欢迎共同探讨。

一、关于QGIS

QGIS 是一个功能强大的桌面GIS软件本身，为用户提供了图形化界面（GUI）来进行地图制作、空间数据管理、空间分析、地理信息可视化等所有GIS任务。它依赖于OSGeo4W，在Windows系统上，官方推荐的QGIS安装方式就是通过OSGeo4W安装器。当你从QGIS官网下载Windows安装程序时，你实际上下载的是OSGeo4W安装器的一个精简版，它会自动为你安装QGIS和其最小所需的依赖项。

二、关于OSGeo4W

OSGeo4W 是一个用于分发开源地理信息系统（OSGeo）软件的 安装包管理系统，而 QGIS 是它管理的 最重要的软件之一。它的主要工作是下载、安装、更新和管理一大批在Windows上运行的开源GIS软件及其所有的依赖库。

“依赖库”是什么？ 像QGIS这样的复杂软件并非完全独立开发，它需要调用许多其他人写好的基础功能库（例如用于处理GDAL地理数据、PROJ坐标投影、GEOS几何运算等）。这些库就是“依赖”。手动管理这些依赖非常复杂且容易出错。

OSGeo4W 完美解决了这个问题。它提供了一个命令行和图形化界面，让你可以轻松地：选择QGIS，它会自动把所有需要的依赖库（GDAL, PROJ, GEOS等）都一并安装好；你还可以通过它安装GRASS GIS、SAGA GIS、gvSIG等 dozens 种其他GIS软件和命令行工具；可以同时安装QGIS的长期发布版（LTR）和最新开发版（Nightly），并轻松切换；用一个命令就能更新所有已安装的软件和库到最新版本。

三、版本信息

Visual Studio：2022

QGIS（LTR）：3.44.2

Qt：5.15.13

四、下载QGIS+QT

OSGeo4W官网下载地址：Download · QGIS Web Site

点击下载，下载成功后如图所示：

右击以管理员身份运行（很重要！！！），进入安装向导。

设置存储路径，笔者存储在F:\OSGeo4W，注意如果刚刚没有以管理员身份运行的话，这里无法选择All Users。

选择第一个网址，继续点击下一页。

根据自己需要选择不同版本：

长期发行版（LTR）,以qgis-ltr列出
开发版（DEV）,以qgis-dev列出
Desktop: 桌面版
Libs：开发版

特性	LTR (Long-Term Release) 长期支持版	DEV (Development) / 常规版
定位	稳定、可靠、用于生产环境	新功能、前沿、用于测试和体验
更新频率	低（约每一年发布一个新的大版本）	高（约每四个月发布一个新的大版本）
支持周期	长（每个版本发布后，会提供至少一年的bug修复和安全更新）	短（通常只支持到下一个常规版发布）
稳定性	非常高。经过充分测试，bug较少。	较低。包含最新代码，可能引入新的未知bug和API变动。
新功能	较少。版本发布时的新功能在后续一年内基本冻结。	非常多。第一时间包含所有最新功能和改进。
适用场景	商业项目、科研项目、生产环境、系统集成、二次开发	QGIS核心开发者、功能测试者、急于体验最新功能的高级用户

笔者选择下载ltr版本，为了让开发环境完整且正常工作，需要安装以下两个组件：

1. 从Desktop分类安装：qgis-ltr (运行时环境)

这是什么？ 这是完整的 QGIS 桌面应用程序本身和所有它运行所需的运行时库（DLL 文件）。
为什么需要？ 当在 Visual Studio 中编译完成二次开发程序后，要让它能运行起来，就必须有这些 DLL 文件。您的程序不是独立存在的，它需要调用这些 QGIS 的动态链接库。

2. 从Libs分类安装：qgis-ltr-devel (开发包)

这是什么？ 这是开发包。它不包含可执行程序，只包含编译所需的头文件 (.h) 、导入库文件 (.lib) 和用于生成文档的文件。
为什么需要？ 当在 Visual Studio 中编写代码时，#include <qgsmapcanvas.h> 这样的语句需要找到头文件。当链接器工作时，它需要找到 qgis_core.lib 这样的库文件来生成你的.exe文件。这个包就提供了这些文件。

一个重要提示：当选择安装qgis-ltr-devel时，安装器会自动标记并安装所有它依赖的其他开发包（如gdal-devel，proj-devel，qt5-devel 等），这是最省心、最不容易出错的方式。

安装操作如下，输入qgis-ltr，点击Desktop下的Skip，点击后会显示版本号，注意不要点击Enter键。

qgis-ltr这个包只包含了运行QGIS桌面软件所必需的可执行文件（.exe）、动态链接库（.dll）和资源文件。它的目的是让用户能够打开并使用QGIS软件进行绘图和分析，而不是为了开发。要进行二次开发需要的是头文件（.h）、导入库（.lib）和用于调试的符号文件（.pdb），这些都在devel包里。继续输入qgis-ltr-devel，点击Libs下的Skip，点击后显示版本号。

OSGeo4W中的QGIS及其所有依赖库（GDAL、PROJ等）都是使用特定版本的Qt（通常是Qt 5.15.x）和特定编译器（MSVC）编译的。如果从Qt官网下载另一个版本的Qt，或者用不同编译器（如MinGW）编译的Qt，会产生二进制不兼容问题，导致链接失败或运行时崩溃。

所以继续在OSGeo4W上安装Qt5开发包，继续输入qt5-devel，进行同样的操作，点击Libs下的Skip，点击后显示版本号，点击下一页安装。
注意：Qt 版本一定是5.15.x，QGIS 3.x 系列与 Qt 6 不兼容。

安装完成如下图。

五、环境配置

打开Visual Studio 2022，点击菜单栏的扩展—管理扩展，然后在右上角搜索框中输入Qt，找到Qt Visual Studio Tools（通常由Qt Company提供），点击“下载”。下载完成后，关闭所有VS窗口，安装程序会自动运行，安装完成后重新打开VS。

重新打开Visual Studio，点击菜单栏的扩展—Qt VS Tools—Options—Versions，在弹出的窗口中，点击右侧的Add 按钮。添加一个新的Qt版本：

Name: 取一个容易识别的名字，例如QtOSGeo4W

Location: 浏览到OSGeo4W中的Qt目录，笔者设置的地址是F:\OSGeo4W\apps\Qt5

点击确定保存，现在VS就知道去哪里找到Qt的编译工具和库文件了。

在VS2022中创建QT Widegets项目，由于QGIS二次开发环境必须在Release环境下才能运行，因此将Debug删去，只保留Release版本。其他默认下一步，成功创建项目。

设置项目属性，右键项目，选择属性—C/C++—常规—附加包含目录，添加下载的OSGeo4W的相关库存储路径：

F:\OSGeo4W\apps\qgis-ltr\include

F:\OSGeo4W\apps\Qt5\include

F:\OSGeo4W\apps\Qt5\include\QtCore

F:\OSGeo4W\apps\Qt5\include\QtWidgets

F:\OSGeo4W\apps\Qt5\include\QtXml

F:\OSGeo4W\apps\Qt5\include\QtGui（根据自己设置的安装路径修改）

选择链接器—常规—附加库目录，添加下载的OSGeo4W的相关库存储路径：

F:\OSGeo4W\apps\Qt5\lib

F:\OSGeo4W\apps\qgis-ltr\lib（根据自己设置的安装路径修改）

选择链接器—输入—附加依赖项，添加以下内容：

qgis_core.lib

qgis_app.lib

qgis_gui.lib

Qt5Core.lib

Qt5Gui.lib

Qt5Widgets.lib

选择C/C++—预处理器—预处理器定义，输入：_USE_MATH_DEFINES

选择常规—C++语言标准，设置为 ISO C++17标准（/std:c++17）。

输入以下示例代码，注意修改成自己的路径，图层路径不要出现中文：

#include "QGIS.h"//修改为自己的项目名
#include <QtWidgets/QApplication>
#include <qgsapplication.h>
#include <qgsmapcanvas.h>
#include <qgsrasterlayer.h>
#include <qgsmaptoolpan.h>
#include <QDebug>
#include <QDir> // 添加这个头文件int main(int argc, char* argv[])
{// 设置PROJ库的环境变量 - 这是关键！// 根据您的OSGeo4W安装路径调整qputenv("PROJ_LIB", "F:/OSGeo4W64/share/proj");// 使用QgsApplication代替QApplication，并启用GUIQgsApplication a(argc, argv, true);// 设置QGIS的安装路径（根据您的实际安装路径修改）QgsApplication::setPrefixPath("F:/OSGeo4W64/apps/qgis-ltr", true);// 初始化QGIS资源QgsApplication::initQgis();QMainWindow main_window;QgsMapCanvas map_canvas;// 创建栅格图层，指定TIFF文件路径QgsRasterLayer layer(R"(F:\GIS-TA\QGIS\QGIS\rs.tif)", "My Raster Layer");// 将图层添加到画布map_canvas.setLayers({ &layer });map_canvas.setExtent(layer.extent());map_canvas.refresh();QgsMapToolPan map_tool_pan(&map_canvas);map_canvas.setMapTool(&map_tool_pan);main_window.setCentralWidget(&map_canvas);main_window.resize(800, 600);main_window.show();int exit_code = a.exec();// 清理QGIS资源QgsApplication::exitQgis();return exit_code;
}

若出现如下的错误：

这是因为代码（使用的某个第三方库，比如QGIS或其依赖库的代码）使用了微软标准库扩展（STL Extensions）中的功能：stdext::make_checked_array_iterator 和相关的迭代器。这些功能（以 stdext:: 开头）是微软独有的、非C++标准的扩展。微软警告说，这些扩展在未来的版本中会被移除，不再支持。
解决方案：

在“解决方案资源管理器”中，右键点击你的项目 -> “属性”。在属性页中，导航到 “配置属性” -> “C/C++” -> “预处理器”。点击 “预处理器定义” 这一项右边的下拉箭头，选择 “编辑...”，在弹出的对话框中，点击右上角的 “新建” 图标。添加宏定义：_SILENCE_STDEXT_ARR_ITERS_DEPRECATION_WARNING