企业官网建设流程全解析

简介：本资源为基于源码编译完成的QGIS工程文件，面向从事GIS二次开发、桌面端地图应用搭建的开发者与测绘、地信专业学习者。使用CMAKE配合Visual Studio 2019与QT5.15.2编译成功，亲测可直接打开工程运行，包含常用GIS功能模块，开发者可在此基础上自行增删模块，省去从零配置编译环境的繁琐过程。压缩包共8183个文件，约473.47MB，以svg图标资源、h头文件、txt说明、png图片、py脚本、dll动态库、qgm与qm语言文件、ui界面文件等为主，另有少量cpp源码、shp矢量样例与xml配置，覆盖界面、翻译、插件与依赖库等完整结构。目前已有1211人学习下载。工程目录层次清晰，便于按模块定位代码与资源，适合作为QGIS定制开发、功能裁剪与编译调试的起点，也可用于学习大型C++/QT项目的组织方式与依赖管理。

1. 拿到一份 QGIS 编译工程文件，先别急着双击 .sln

很多人第一次接触 QGIS 二次开发，卡住的地方不是写代码，而是环境。源码下载下来几十个 G，CMake 配置报错、依赖找不到、Qt 版本对不上，光编译就能耗掉两三天。这份资源解决的正是这个最劝退的环节——它是一份已经用 CMAKE + VS2019 + QT5.15.2 编译通过的 QGIS 工程文件，包含基本功能模块，下载后直接用 Visual Studio 2019 打开工程就能跑起来。

它适合三类人：想基于 QGIS 做插件或独立 GIS 应用的开发者、需要裁剪 QGIS 功能模块做定制系统的团队、以及被源码编译反复折磨想先拿到一个能跑环境再研究的工程师。资源里附带的.api文件（PyQGIS.api、PyQt5.api、QScintilla2 系列、OSGeo_GDAL-OGR-2.2.3.api 等）是给 IDE 做代码补全和跳转用的，说明这套工程不只是能编译，还考虑到了后续写代码的体验。下面从工程结构、编译配置、模块裁剪到排错，一步步拆开讲。

2. 工程文件里到底有什么：目录结构与 .api 补全文件的作用

2.1 从 .sln 到模块目录，先认清这套工程的组织方式

拿到压缩包解压后，根目录下会有一个.sln解决方案文件，这是 VS2019 的入口。用 VS2019 打开它，解决方案资源管理器里会列出几十个项目，这些项目大致分几类：核心库（qgis_core）、界面库（qgis_gui）、应用程序（qgis_app）、以及各个功能模块（分析、栅格、矢量、网络分析等）。每个项目对应源码树里的一个子目录，编译产物是.dll和.lib。

和纯源码包不同的是，这份工程已经把 CMake 生成步骤做完了。正常流程是：装 CMake → 配 CMakeLists.txt → 指定依赖路径 → generate 出 VS 工程 → 再打开 .sln。这份资源跳过了前面几步，直接给你 generate 之后的成果。所以打开就能看到项目结构，不用再跟 CMake 的Could NOT find报错纠缠。

但要注意，工程文件里的路径是编译者机器上的绝对路径。如果你解压到的目录和原作者不一致，VS 会提示找不到头文件或库。这是第一个要处理的地方，后面排错章节会细说。

2.2 .api 文件不是可执行文件，别拿它当库去链接

资源里列出的 PyQGIS.api、PyQt5.api、PyQGIS-2.2.api、Python-3.6.api、QScintilla2-2.7.2.api、OSGeo_GDAL-OGR-2.2.3.api 这些，扩展名是.api，很多人第一次见会懵。它不是动态库，也不是编译产物，而是 Qt Creator / VS 配合 Qt VS Tools 做代码补全用的接口描述文件。

具体来说，.api文件里记录了某个库暴露出来的类、方法、参数签名。IDE 读了这个文件，你在写QgsVectorLayer或QgsFeature的时候才能有自动补全和跳转。PyQGIS.api 对应 Python 绑定层的补全，PyQt5.api 对应 PyQt5 的补全，QScintilla2 系列对应代码编辑器控件的补全，OSGeo_GDAL-OGR 那个对应 GDAL/OGR 库的补全。

这些文件要放到 IDE 能识别的位置。VS2019 配合 Qt VS Tools 时，一般放在 Qt 的api目录或者工程指定的补全路径下。放错了不会导致编译失败，但写代码时没有补全，效率会低很多。多个版本的 PyQGIS.api 并存，是为了兼容不同 QGIS 版本的 API 差异，你按自己工程用的 QGIS 版本选对应的那个即可。

2.3 功能模块的划分逻辑，决定了你后面怎么裁剪

QGIS 的模块化程度很高，核心库和功能模块是分开的。核心库提供基础的空间数据模型、坐标系转换、渲染引擎；功能模块则按业务领域拆分，比如栅格分析、矢量分析、网络分析、GPS 工具等。这份工程包含的是「基本功能模块」，意味着常用的矢量栅格处理、图层管理、地图渲染这些都在，但一些偏门或依赖第三方重型库的模块可能没编进去。

这种划分对二次开发很友好。你要做一个只用到矢量编辑的工具，就可以在解决方案里把栅格分析相关的项目卸载掉，减少编译时间和最终体积。反过来，如果你需要某个没编进来的模块，也可以把对应源码目录加回 CMakeLists.txt 重新 generate。前提是你得先搞清楚每个项目对应哪个功能，这个在解决方案资源管理器里看项目名基本能判断，项目名和源码目录名是对应的。

3. 用 VS2019 打开工程并跑起来：配置、编译、启动的完整链路

3.1 打开前的环境核对，少一个都编译不过

在双击 .sln 之前，先把这几样东西确认好，否则打开后就是一片红。第一，VS2019 必须装了「使用 C++ 的桌面开发」工作负载，里面包含 MSVC 编译器和 Windows SDK。第二，Qt 5.15.2 要装好，并且和 VS2019 的版本匹配（msvc2019 64bit）。第三，Qt VS Tools 扩展要装，VS2019 里通过「扩展 → 管理扩展」搜索安装。第四，GDAL/OGR 的运行库要在系统 PATH 里，或者工程里配了正确的库目录。

这几样里最容易出问题的是 Qt 版本。Qt 5.15.2 有 msvc2019 32bit 和 64bit 两个版本，工程编译时用的是哪个，你就得装哪个。装错了会在链接阶段报一堆LNK2019 无法解析的外部符号，看起来像代码问题，其实是架构不匹配。

3.2 用 CMake 重新 generate 一份适配自己路径的工程

虽然资源给的是编译好的工程，但路径大概率和你机器对不上。稳妥做法是用 CMake 重新 generate 一次，让它把路径改成你的。前提是源码目录还在，且 CMakeLists.txt 完整。

# 在源码根目录下新建 build 目录，避免污染源码树 mkdir build cd build # 指定 VS2019 64 位生成器，指定 Qt5 的路径和 GDAL 路径 cmake -G "Visual Studio 16 2019" -A x64 ^ -DCMAKE_PREFIX_PATH="C:/Qt/5.15.2/msvc2019_64" ^ -DGDAL_INCLUDE_DIR="C:/OSGeo4W/include" ^ -DGDAL_LIBRARY="C:/OSGeo4W/lib/gdal_i.lib" ^ .. # 生成成功后，build 目录下会出现 QGIS.sln

这段命令的关键参数：-G "Visual Studio 16 2019"指定生成 VS2019 工程，-A x64指定 64 位架构，必须和 Qt 版本一致。CMAKE_PREFIX_PATH指向 Qt 安装目录，CMake 靠它找 Qt 的库和头文件。GDAL_INCLUDE_DIR和GDAL_LIBRARY指向 GDAL 的头文件和导入库，路径按你实际安装位置改。

如果 CMake 报Could NOT find Qt5，先检查CMAKE_PREFIX_PATH里的路径是否存在，再确认 Qt 安装时勾选了 msvc2019_64 组件。如果报 GDAL 相关找不到，检查 OSGeo4W 是否装了开发包（不是只装运行时）。

3.3 在 VS2019 里编译并指定启动项目

generate 成功后，用 VS2019 打开 build 目录下的.sln。这时候解决方案资源管理器里项目齐全，但启动项目可能没设对。QGIS 的主程序项目一般叫qgis或qgis_app，右键它 →「设为启动项目」。

编译前先选配置：Debug 还是 Release。Debug 版带调试符号，能断点跟踪，但体积大、运行慢；Release 版优化过，跑得快，适合最终测试。第一次建议用 Release，因为 Debug 版对依赖库的调试版本有要求，如果 GDAL 只装了 Release 库，Debug 链接会失败。

# 在 VS 里也可以直接用 msbuild 命令行编译，适合脚本化 msbuild QGIS.sln /p:Configuration=Release /p:Platform=x64 /m # /m 表示多核并行编译，能明显缩短时间 # 编译产物在 build/output/Release 下

编译过程视机器性能，大概十几分钟到半小时。编译完成后，在输出目录找到qgis.exe或对应的可执行文件，双击应该能启动 QGIS 界面。如果启动时报缺 DLL，用 Dependency Walker 或 VS 自带的「模块」窗口看缺哪个，把对应 DLL 拷到 exe 同目录，或把库目录加进 PATH。

3.4 验证编译是否真的成功，别只看有没有报错

编译不报错不等于能跑。验证分三步：第一步，看输出目录下qgis_core.dll、qgis_gui.dll、qgis_app.exe这些核心产物是否都生成了。第二步，双击 exe，看主界面能不能正常出来，菜单栏、工具栏、图层面板是否完整。第三步，加载一个 shapefile 或 GeoTIFF，看渲染是否正常，这能验证 GDAL/OGR 和渲染引擎是否工作。

如果界面出来了但加载数据崩溃，大概率是 GDAL 数据驱动没找到，检查GDAL_DATA环境变量是否指向 GDAL 的 data 目录。如果界面都出不来，看 Windows 事件查看器里的应用程序日志，通常会有缺 DLL 的记录。

4. 模块裁剪与二次开发：怎么在现有工程上加功能、删模块

4.1 卸载不需要的项目来缩短编译时间

全量编译 QGIS 很耗时，如果你只做矢量相关开发，栅格分析、网络分析这些模块完全可以先卸载。在 VS2019 解决方案资源管理器里，右键不需要的项目 →「卸载项目」。卸载不是删除，后面需要了再「重新加载项目」即可。

哪些项目能安全卸载？原则是看依赖关系。qgis_core和qgis_gui是基础，不能卸。qgis_app是主程序，做独立应用的话要保留。分析类模块（analysis、raster、network）如果不用对应功能，可以卸。但要注意，有些模块之间有隐式依赖，卸了之后编译主程序可能报找不到符号。稳妥做法是一次卸一两个，编译验证通过再继续。

4.2 新增自定义模块的接入点

要在现有工程里加自己的功能模块，常见做法是新建一个项目，输出为 DLL，然后让主程序在启动时加载。QGIS 的插件机制本身就是这么设计的。你可以在源码树的src/plugins目录下仿照现有插件建目录，写自己的CMakeLists.txt，然后在顶层 CMakeLists.txt 里add_subdirectory加进去。

# 自定义模块的 CMakeLists.txt 骨架 set(MYMODULE_SRC mymodule.cpp mymodule.h) add_library(mymodule SHARED ${MYMODULE_SRC}) # 链接 QGIS 核心库 target_link_libraries(mymodule qgis_core qgis_gui ) # 指定头文件路径 target_include_directories(mymodule PRIVATE ${CMAKE_SOURCE_DIR}/src/core ${CMAKE_SOURCE_DIR}/src/gui )

这个骨架里，add_library的SHARED表示生成动态库。target_link_libraries把 QGIS 核心库链进来，你的模块才能用QgsVectorLayer这些类。target_include_directories指定头文件搜索路径，路径按实际源码结构改。写完 CMakeLists.txt 后重新 generate，新项目就会出现在解决方案里。

4.3 调试时怎么挂载到 QGIS 进程

做插件或模块开发，调试是刚需。在 VS2019 里，把主程序qgis_app设为启动项目，然后在你的模块代码里打断点。按 F5 启动调试，QGIS 起来后触发你模块的逻辑，断点就会命中。如果断点显示「不会命中」，检查你的模块 DLL 是否被正确加载，以及调试配置里是否勾选了「启用本机代码调试」。

另一种方式是用「附加到进程」。先正常启动 QGIS，然后在 VS 里「调试 → 附加到进程」，找到qgis.exe附加。这种方式适合调试已经跑起来的实例，不用每次重启。

5. 避坑与排查：编译 QGIS 工程最常见的五个翻车点

5.1 现象：CMake 配置时报 Could NOT find Qt5，明明装了 Qt

原因通常有三个：CMAKE_PREFIX_PATH没设或设错、Qt 安装时没勾选对应编译器组件、环境变量里有多个 Qt 版本冲突。解决方法是先确认C:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5这个目录存在，然后在 CMake 命令里显式指定-DCMAKE_PREFIX_PATH到这个路径。如果还不行，检查系统 PATH 里有没有其他 Qt 版本的 bin 目录，有就先移除。

5.2 现象：链接阶段报大量 LNK2019 无法解析的外部符号

这是架构不匹配的典型症状。Qt 装的是 32 位，工程 generate 的是 64 位，或者反过来。解决方法是统一架构：确认 Qt 是 msvc2019_64，CMake 用-A x64，VS 里配置管理器也选 x64。另一个可能是 GDAL 库的位数不对，同样要统一。

5.3 现象：编译通过但启动时提示缺少 Qt5Core.dll 等

运行时找不到 Qt 的 DLL。原因是没有把 Qt 的 bin 目录加进 PATH，或者没有用windeployqt把依赖拷到 exe 同目录。解决方法是在 VS 的调试配置里，把 Qt 的 bin 目录加到「环境」里，或者编译后手动运行windeployqt qgis_app.exe自动拷贝依赖。

5.4 现象：加载栅格数据时崩溃，矢量数据正常

GDAL 的数据驱动没找到。QGIS 依赖 GDAL 读写各种格式，GDAL 又依赖GDAL_DATA环境变量指向它的 data 目录（里面有坐标系定义、格式描述等）。解决方法是设置GDAL_DATA环境变量，指向 OSGeo4W 或 GDAL 安装目录下的share/gdal或data目录。设置完重启 VS 或重新登录使环境变量生效。

5.5 现象：改了源码重新编译，但运行结果没变化

编译产物没更新，或者运行的是旧版 DLL。原因可能是 VS 没检测到文件变更，或者输出目录里有多个版本的 DLL 冲突。解决方法是先「重新生成解决方案」而不是「生成」，确保全量编译。然后检查输出目录里 DLL 的时间戳，确认是刚编译出来的。如果还不行，手动删除输出目录再编译一次。

6. 从能跑到好用：用 .api 补全和调试配置把开发效率提上来

工程能跑起来只是第一步，真正做开发时，代码补全和调试效率决定了你一天能写多少。前面提到的那些.api文件，配好了能让 VS2019 在写 PyQGIS 或 C++ 代码时给出准确的类成员提示，不用频繁翻文档。

配置 .api 补全的常见做法是：在 VS2019 里装 Qt VS Tools 后，打开「Qt VS Tools → Qt Options」，确认 Qt 版本路径正确。然后在「工具 → 选项 → Qt VS Tools → IntelliSense」里，把.api文件所在目录加进去。如果你用的是 Qt Creator，则在「工具 → 选项 → 环境 → 定位器」里配置。配好后，输入Qgs开头的类名，会自动列出所有匹配的 QGIS 类。

调试配置上，我一般会做两件事。第一，在 VS 的「调试 → 选项 → 符号」里，把 Qt 和 GDAL 的 PDB 符号路径加进去，这样调试时能进到 Qt 和 GDAL 的源码里，排查底层问题时不用猜。第二，给主程序配一个自定义的启动参数，比如直接加载一个测试用的 shapefile，省去每次手动打开数据的步骤。

// VS 调试配置里可以设的启动参数示例（launch.vs.json） { "version": "0.2.1", "defaults": {}, "configurations": [ { "type": "default", "project": "CMakeLists.txt", "projectTarget": "qgis_app.exe", "name": "调试 QGIS 并加载测试数据", "args": ["--project", "C:/test/test.qgs"] } ] }

这个配置让每次 F5 启动时自动加载指定的 QGIS 工程文件，直接进入你要调试的场景，不用手动点菜单。args里的参数按 QGIS 命令行支持的实际参数写，--project后面跟工程文件路径。

还有一个习惯：每次改完 CMakeLists.txt 或加了新源文件，先重新 generate 再编译，不要直接在 VS 里加文件。因为 VS 工程是 CMake 生成的，手动加的文件下次 generate 会丢。从那以后我每次动源码结构，都强制走一遍「改 CMakeLists → 重新 generate → 编译」的流程，省得后面找不到文件在哪。希望帮到你。

本文还有配套的精品资源，点击获取