1. 为什么还要折腾源码编译这套组合QGIS 3.10 是一个长期支持版本很多做地理信息系统的团队至今仍在用它维护存量项目。直接下载官方安装包当然最省事但一旦你要做二次开发、写自定义插件、改底层渲染逻辑或者需要把 QGIS 嵌入到自己的桌面应用里就必须拿到一套能跟本地开发环境完全对齐的编译产物。VS2019 搭配 QT5.14 是 Windows 平台上比较稳的一组工具链QGIS 3.10 的源码对这两个版本的兼容性也经过了大量验证。这套编译流程解决的核心问题是让你在 Windows 上从零得到一套可调试、可修改、可重新打包的 QGIS 开发环境。适合的人群包括 GIS 桌面端开发、需要定制 QGIS 功能的技术团队以及想深入理解 QGIS 架构的进阶用户。整个过程涉及依赖管理、CMake 配置、编译参数调优和运行时环境修复坑不少但只要按顺序走成功率很高。我前后完整编译过好几轮第一次花了整整两天后来摸清套路后半天就能跑通。下面把整套流程拆开讲包括每一步背后的原因和实际踩过的坑。2. 编译前的整体思路与环境规划2.1 为什么选 VS2019 QT5.14 这个组合QGIS 3.10 的官方 Windows 构建在当年主要基于 MSVC 2017/2019 和 QT 5.11~5.14。选 VS2019 是因为它对 C17 的支持更完整而且社区版的免费授权对个人和中小团队足够用。QT5.14 是 QT5 系列里比较成熟的一个版本QGIS 3.10 的源码里大量使用了 QT5 的模块包括 QtCore、QtGui、QtWidgets、QtXml、QtSvg、QtNetwork、QtSql、QtWebKit 或 QtWebEngine 等。这里有个关键点QT 的版本必须和 QGIS 源码要求的版本匹配。QGIS 3.10 的 CMakeLists 里对 QT 最低版本有明确要求用 5.14 是安全的但如果你手头只有 5.12也能编只是个别模块可能需要打补丁。我建议直接用 5.14.x 的最后一个补丁版本稳定性最好。2.2 依赖清单与获取渠道编译 QGIS 不是只装 QT 和 VS 就够的它依赖一大堆第三方库。核心依赖包括GDAL栅格和矢量数据抽象库QGIS 的数据读写全靠它GEOS几何运算库空间分析的基础PROJ坐标投影转换库QGIS 3.x 之后 PROJ 升级到 6.x 以上变化很大SQLite / SpatiaLite本地空间数据库支持QWT图表绘制库用于 QGIS 的图表工具QScintilla代码编辑器组件QGIS 的表达式编辑器用到PythonQGIS 的 Python 绑定和插件系统依赖Flex / Bison语法解析器生成工具编译某些模块时需要这些依赖有两种获取方式一是自己逐个编译二是用 OSGeo4W 提供的预编译包。对于第一次编译的人我强烈建议用 OSGeo4W 的库能省掉大量时间。但要注意OSGeo4W 的库是用特定编译器版本构建的混用不同版本的 MSVC 运行时可能出问题。所以要么全用 OSGeo4W 的要么全自己编别混着来。2.3 目录结构规划在动手之前先把目录规划好后面会省很多事。我习惯这样安排D:\qgis_build\ src\ # QGIS 源码 build\ # CMake 构建目录 install\ # 编译产物安装目录 deps\ # 第三方依赖 include\ lib\ bin\把源码、构建、安装、依赖分开好处是重新编译时不会污染源码目录出问题也容易清理。构建目录和安装目录一定要分开CMake 的 out-of-source 构建是基本要求直接在源码目录里构建会搞得一团糟。3. 核心环境搭建与依赖配置实操3.1 VS2019 安装与组件选择VS2019 安装时工作负载选“使用 C 的桌面开发”右侧的单个组件里必须勾选MSVC v142 - VS 2019 C x64/x86 生成工具Windows 10 SDK版本选一个较新的比如 10.0.19041.0C CMake 工具如果你不想单独装 CMake适用于 Windows 的 C Clang 工具可选但有些依赖编译会用到安装路径建议默认不要改到中文路径下。我见过有人把 VS 装到带中文的目录结果 CMake 配置时各种路径解析错误排查了半天。3.2 QT5.14 安装与模块勾选QT 用在线安装器装版本选 5.14.2。组件里必须勾选MSVC 2017 64-bit这个组件在 VS2019 下也能用QT 官方没有单独的 VS2019 构建MSVC 2017 的二进制兼容Qt ChartsQGIS 的图表功能需要Qt WebEngine如果要用 QGIS 的内嵌浏览器Qt Script部分旧插件依赖Sources可选但调试时能跟进去看 QT 内部实现装完后把 QT 的 bin 目录加到系统 PATH 里比如D:\Qt\Qt5.14.2\5.14.2\msvc2017_64\bin。这一步很重要后面 CMake 找 QT 和运行时加载 DLL 都靠它。3.3 OSGeo4W 依赖安装下载 OSGeo4W 的安装器选“高级安装”然后从网络安装。在包选择界面搜索并勾选以下开发包gdal-devgeos-devproj-devsqlite3-devspatialite-devqwt-devqscintilla-devpython3-devel安装路径建议放在D:\OSGeo4W64。装完后这个目录下会有include、lib、bin等子目录CMake 配置时需要指向这里。注意OSGeo4W 的库版本要和 QGIS 3.10 的要求匹配。如果 OSGeo4W 更新了 GDAL 到 3.5 以上而 QGIS 3.10 的源码只支持到 GDAL 3.0就会编译失败。这种情况下要么降级 OSGeo4W 的包要么自己编译指定版本的 GDAL。3.4 CMake 与 Ninja 配置CMake 建议用 3.16 以上的版本Ninja 作为生成器比 MSBuild 快很多。装好 CMake 后把cmake.exe和ninja.exe的路径加到 PATH。验证环境是否就绪打开命令行执行cmake --version ninja --version clcl命令能输出版本信息说明 VS 的环境变量已经生效。如果cl不识别需要先运行 VS 的开发者命令提示符或者手动调用vcvars64.bat。4. 源码获取与 CMake 配置全流程4.1 源码下载与版本确认QGIS 3.10 的源码可以从官方仓库获取切换到release-3_10分支。用 git 克隆git clone -b release-3_10 https://github.com/qgis/QGIS.git qgis_src克隆完成后进入源码目录确认一下CMakeLists.txt里的版本号是 3.10.x。如果网络不稳定也可以下载对应版本的源码压缩包。源码目录里有个INSTALL.md里面列出了所有依赖和编译选项值得先扫一遍。虽然它主要针对 Linux但依赖列表和 CMake 选项是通用的。4.2 CMake 关键参数逐项解读在 build 目录里执行 CMake 配置命令比较长我拆开解释每个参数cmake -G Ninja ^ -DCMAKE_BUILD_TYPERelWithDebInfo ^ -DCMAKE_INSTALL_PREFIXD:/qgis_build/install ^ -DCMAKE_PREFIX_PATHD:/Qt/Qt5.14.2/5.14.2/msvc2017_64;D:/OSGeo4W64 ^ -DWITH_3DOFF ^ -DWITH_APIDOCOFF ^ -DWITH_SERVERON ^ -DWITH_PYTHONON ^ -DENABLE_TESTSOFF ^ ../srcCMAKE_BUILD_TYPERelWithDebInfo带调试信息的发布版既能跑得快又能调试。纯 Debug 版太慢纯 Release 版没法跟栈。CMAKE_INSTALL_PREFIX安装目录编译完ninja install会装到这里。CMAKE_PREFIX_PATH告诉 CMake 去哪里找 QT 和 OSGeo4W 的库多个路径用分号隔开。WITH_3DOFF3D 模块依赖 QT3D编译麻烦且容易出错不需要就关掉。WITH_APIDOCOFFAPI 文档生成需要 Doxygen编译时不需要。WITH_SERVERON如果需要 QGIS Server 就打开只做桌面端可以关。WITH_PYTHONONPython 绑定插件开发必备。ENABLE_TESTSOFF测试编译很耗时第一次编译建议关掉。配置过程中CMake 会输出一堆Found XXX或Could NOT find XXX。重点关注那些Could NOT find的项如果是核心依赖GDAL、GEOS、PROJ、QT必须解决如果是可选依赖比如 GRASS、SAGA可以暂时忽略。4.3 常见配置错误与修复错误一找不到 QT5报错信息类似Could not find a package configuration file provided by Qt5。原因是CMAKE_PREFIX_PATH没指对或者 QT 的Qt5Config.cmake不在预期位置。检查 QT 安装目录下是否有lib/cmake/Qt5这个路径确保CMAKE_PREFIX_PATH指向的是 QT 的根目录即包含lib和bin的那一层。错误二PROJ 版本不匹配QGIS 3.10 要求 PROJ 6.x 以上。如果 OSGeo4W 装的是 PROJ 5.xCMake 会报版本错误。解决办法是升级 OSGeo4W 的 proj-dev 包或者手动编译 PROJ 6.x 并指定路径。错误三Python 相关找不到如果WITH_PYTHONON但 CMake 找不到 Python需要指定-DPYTHON_EXECUTABLE和-DPYTHON_INCLUDE_DIR、-DPYTHON_LIBRARY。OSGeo4W 里有 Python3路径通常在D:/OSGeo4W64/bin/python3.exe。配置成功后CMake 会生成build.ninja文件。这时候别急着编译先检查一下CMakeCache.txt里的关键变量是否符合预期。5. 编译过程与运行时环境修复5.1 编译执行与耗时预估用 Ninja 编译ninja如果机器是多核的Ninja 默认会用满所有核心。我实测在 8 核 16 线程的机器上完整编译大约 40 分钟到 1 小时。如果内存不足 16GB建议限制并行数否则链接阶段可能爆内存ninja -j 4编译过程中最常见的错误是某个源文件编译失败通常是头文件路径问题或依赖版本不匹配。Ninja 会停在出错的地方并打印错误信息根据提示逐个解决。5.2 安装与 DLL 依赖收集编译完成后执行安装ninja install安装目录下会有bin、lib、include、share等子目录。但这时候直接运行qgis.exe大概率会报缺 DLL。因为 QGIS 依赖的 QT DLL、GDAL DLL、PROJ DLL 等都不在安装目录里。解决办法有两种一是把 QT 和 OSGeo4W 的 bin 目录加到系统 PATH二是用windeployqt工具把 QT 的 DLL 拷到安装目录再手动拷 GDAL、GEOS、PROJ 等 DLL。我推荐第二种做出来的安装目录更独立方便分发。windeployqt --release D:/qgis_build/install/bin/qgis.exe然后从 OSGeo4W 的 bin 目录里把gdal*.dll、geos*.dll、proj*.dll、sqlite3.dll、spatialite*.dll等拷过来。具体缺哪些运行一次qgis.exe看报错弹窗里缺什么就补什么。5.3 环境变量与插件路径配置QGIS 运行时需要知道去哪里找 PROJ 的坐标数据、GDAL 的数据文件、QGIS 的插件和资源。这些通过环境变量或配置文件指定PROJ_LIB指向 PROJ 的share/proj目录GDAL_DATA指向 GDAL 的share/gdal目录QGIS_PREFIX_PATH指向 QGIS 安装目录QT_PLUGIN_PATH指向 QT 的plugins目录可以在系统环境变量里设也可以写一个启动脚本qgis.batecho off set QGIS_PREFIX_PATHD:\qgis_build\install set PROJ_LIBD:\qgis_build\install\share\proj set GDAL_DATAD:\qgis_build\install\share\gdal set QT_PLUGIN_PATHD:\Qt\Qt5.14.2\5.14.2\msvc2017_64\plugins set PATHD:\qgis_build\install\bin;D:\Qt\Qt5.14.2\5.14.2\msvc2017_64\bin;%PATH% start D:\qgis_build\install\bin\qgis.exe这样每次双击这个 bat 就能启动不用污染系统环境变量。5.4 调试环境配置如果要在 VS2019 里调试 QGIS需要把qgis.exe设为启动项目并配置调试符号路径。编译时用了RelWithDebInfo所以bin目录下有对应的.pdb文件。在 VS 的“调试”-“选项”-“符号”里把安装目录的bin加进去就能在断点处看到源码行号。调试时经常需要看 QT 内部的调用栈这时候需要 QT 的调试符号。QT 在线安装器里可以单独下载调试信息包或者从 QT 的源码自行编译带调试符号的版本。这一步比较耗时非必要不折腾。6. 常见问题速查与避坑经验6.1 编译期问题速查表问题现象可能原因解决办法CMake 找不到 Qt5CMAKE_PREFIX_PATH 未指向 QT 根目录检查路径确保包含 lib/cmake/Qt5PROJ 版本过低OSGeo4W 的 proj-dev 版本旧升级包或手动编译 PROJ 6.x链接时缺 python3x.libPython 库路径未指定设置 PYTHON_LIBRARY 变量编译到一半内存不足并行数过高用 ninja -j 4 限制并行某个 .cpp 报语法错误编译器版本或标准不匹配确认 CMAKE_CXX_STANDARD 为 17找不到 qwt_plot.hQWT 头文件路径未包含在 CMAKE_PREFIX_PATH 里加 QWT 路径6.2 运行期问题与修复问题启动时报“无法定位程序输入点于 XXX.dll”这是典型的 DLL 版本冲突。系统 PATH 里可能有多个版本的 QT 或 GDALQGIS 加载了错误的那个。解决办法是确保启动脚本里的 PATH 顺序正确QGIS 自己的 bin 目录排在最前面。问题坐标转换失败提示找不到 proj.dbPROJ 6.x 之后坐标数据从文本文件改成了 SQLite 数据库proj.db。如果PROJ_LIB没设对或者proj.db不在预期位置就会报这个错。确认PROJ_LIB指向的目录下有proj.db文件。问题Python 插件加载失败QGIS 的 Python 插件需要PYTHONPATH包含 QGIS 的 Python 模块目录。在启动脚本里加上set PYTHONPATHD:\qgis_build\install\python;%PYTHONPATH%同时确认 Python 版本和编译时用的版本一致。6.3 独家避坑心得第一别用中文路径。从源码目录到构建目录到安装目录全用英文一个中文字符都不要有。CMake 和 Ninja 对中文路径的处理时好时坏出了问题很难排查。第二依赖版本要锁死。OSGeo4W 的包会不定期更新今天编通了明天重装一遍可能就编不过了。建议把用到的依赖包版本记录下来或者直接把 OSGeo4W 的安装目录打包备份。第三第一次编译关掉所有非必要模块。3D、Server、测试、文档这些统统关掉先把核心的桌面端编出来。等核心流程跑通了再逐个打开需要的模块重新配置编译。第四保留 CMakeCache.txt。这个文件记录了所有配置参数重新编译时直接复用不用再敲一遍长命令。如果配置乱了删掉 build 目录重新来但 CMakeCache.txt 可以先备份一份。第五编译日志重定向到文件。Ninja 的输出很长终端里翻起来费劲。用ninja build.log 21把日志存下来出错时用文本编辑器搜索error关键字定位快得多。7. 编译产物的验证与后续扩展7.1 功能验证清单编译完成后别急着庆祝先做一轮功能验证启动 QGIS确认主界面正常显示没有缺图标或乱码加载一个 Shapefile 和 GeoTIFF确认数据能正常渲染打开“关于”对话框确认版本号是 3.10.x打开 Python 控制台执行print(qgis.utils.iface)确认 Python 绑定正常创建一个简单的自定义插件确认插件系统能加载测试坐标转换把 WGS84 转到 Web Mercator确认 PROJ 工作正常这些验证过了说明编译产物基本可用。7.2 二次开发环境对接如果要做二次开发需要把 QGIS 的头文件和库链接到自己的项目里。安装目录下的include和lib就是给这个用的。在 VS 项目里配置附加包含目录D:\qgis_build\install\include附加库目录D:\qgis_build\install\lib附加依赖项qgis_core.lib、qgis_gui.lib等写一个最简单的测试程序创建一个QgsApplication实例确认能正常初始化和退出。这一步跑通了后续的开发就顺了。7.3 打包分发注意事项如果要分发给别人用不能只拷qgis.exe。需要把整个安装目录打包包括bin、lib、share、python等子目录。QT 的 DLL 用windeployqt处理其他依赖 DLL 手动补齐。打包前在一台干净的机器上测试一遍确认没有遗漏的运行时依赖。提示打包时可以用 Dependency Walker 或dumpbin /dependents检查每个 DLL 的依赖确保没有遗漏。但注意dumpbin只能看直接依赖间接依赖需要递归检查。7.4 后续升级与维护QGIS 3.10 是 LTS 版本官方会持续发布补丁版本。如果要从 3.10.0 升到 3.10.5不需要重新走一遍完整流程。拉取最新的release-3_10分支代码在原有的 build 目录里重新执行cmake和ninja即可。CMake 会检测到源码变化只重新编译改动的文件速度快很多。但如果依赖库升级了比如 GDAL 从 3.0 升到 3.2可能需要清理 build 目录重新配置。升级依赖前先确认 QGIS 3.10 的源码是否兼容新版本不兼容就暂时别升。我个人在实际操作中的体会是这套编译流程最耗时的部分不是编译本身而是环境配置和依赖排查。第一次走通之后把关键的配置参数、依赖版本、启动脚本都记录下来下次再搭环境就是按图索骥。另外编译过程中遇到报错别慌先看错误信息里的文件路径和行号大部分问题都是路径不对或版本不匹配耐心排查都能解决。