QGIS二次開發01：環境配置-OSGeo4W鏡像

寫在前面：
本筆記根據多方資料整理而成，旨在為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