Windows下MSVC编译QGIS 3.34 LTR完整流程与踩坑指南

编译 QGIS说难也难说简单也简单。难在依赖多、版本杂、报错信息往往不直白简单在于一旦环境理顺剩下就是等进度条。我自己在 Windows 10 上用 MSVC 编译 QGIS 3.34.10 的整个过程前后折腾了两天踩了不少坑也摸出了一套可以稳定复现的流程。这篇就把完整的思路、命令、参数和排查经验整理出来给想编译 QGIS 3.34 系列 LTR 版本的朋友做一个可以直接照抄的参考。QGIS 3.34 是长期支持版本官方安装包用起来很方便但如果你要改 C 源码、做二次开发、定制插件或者想在离线环境里部署自己的构建产物源码编译就是绕不开的一步。这篇文章适合有一定 C 和 CMake 基础、想在 Windows 上拿到自定义 QGIS 可执行文件的开发者也适合刚接触 GIS 二次开发、但愿意按步骤折腾一遍的人。整个流程会涉及 Visual Studio、OSGeo4W、CMake、Ninja、Qt、Python 这些组件我会把每一步为什么要这么做也讲清楚。1. 编译前的整体思路与方案选型1.1 为什么锁定 MSVC 而不是 MinGW很多从 Linux 过来的朋友第一反应是用 MinGW 或 MSYS2 编译毕竟命令行体验更像 Unix。但 QGIS 官方发布的 Windows 包是 MSVC 构建的生态里大量第三方插件、Python 绑定和扩展库也都按 MSVC ABI 编译。ABI 不一致的库硬凑到一起轻则链接报一堆 undefined reference重则运行时直接崩溃。我用 MinGW 试过一次编译本身能过但运行起来时不时出现奇怪的符号冲突尤其是接入 QGIS 的 C 插件时加载一个基于 MSVC ABI 编译的插件就会直接报版本不匹配。所以结论很明确Windows 上老老实实用 MSVCVisual Studio 装好一条路走到黑这是官方支持也是社区验证最多的路径。1.2 依赖管理的三条主流路线QGIS 的依赖非常多光核心库就有 GDAL、GEOS、PROJ、SQLite、Expat、libzip、OpenSSL、QCA、QScintilla、Qt5 等等。把这些依赖全部自己从源码编译一遍工作量巨大不现实。Windows 上通常有三条路依赖方案优点缺点适合场景OSGeo4W 全家桶依赖版本统一、GIS 库齐全、与官方构建最接近包名繁琐、默认带着自己的 Python/Qt 环境绝大多数本地开发者QGIS-DEPS 预编译包自包含、无需折腾包管理、下载即用版本固定、升级不方便、排错时黑盒CI/CD 流水线、快速验证vcpkg / 自己编依赖完全可控、可定制需要编译 GDAL/GEOS 等耗时且维护成本高对依赖有特殊要求的场景我这次选的是第一条路也就是 OSGeo4W 全家桶。原因是它和官方 Windows 安装包的依赖来源一致GDAL、GEOS、PROJ 这些地理库的版本都经过 QGIS 团队验证版本冲突的概率最低。接下来提到的所有配置都以 OSGeo4W 为主线如果你走 QGIS-DEPS 或者 vcpkg思路类似只是 CMAKE_PREFIX_PATH 指向不同目录。1.3 版本匹配3.34.10 的硬性约束QGIS 3.34.10 作为 LTR 版本对编译器、Qt、Python 都有明确要求。别指望随便装个版本就能编译过我整理了一份实测可用的版本组合组件推荐版本说明Visual Studio2019 / 202264 位需要“使用 C 的桌面开发”工作负载Qt5.15.x3.34 系列还没切换到 Qt6别装 Qt6Python3.9 ~ 3.11建议跟着 OSGeo4W 的 python3-core 版本走GDAL3.xOSGeo4W 默认版本即可GEOS3.10同上PROJ8.x / 9.x同上CMake3.24太老版本不识别一些新选项Ninja1.10比 jom 好用报错信息直观版本组合这块最容易翻车的点是 Qt 和 Python。Qt 必须是 MSVC 2019 对应的构建Python 必须和你要用的 PyQt5/sip 版本兼容。我建议 Python 用 3.10 或 3.11太新反而容易遇到 sip 兼容性问题。2. 环境准备与工具链安装2.1 Visual Studio 2019 安装与验证Visual Studio 是 MSVC 编译器的载体安装时不需要全部组件只勾选“使用 C 的桌面开发”这一项工作负载然后在右侧的“单个组件”里确认 Windows 10 SDK 被勾上。如果你磁盘空间紧张这样安装大概占用 10GB 左右编译 QGIS 完全够用。安装完成后建议先在命令行里验证编译器可用。打开“Developer PowerShell for VS 2019”或普通 CMD执行cl如果出现“Microsoft (R) C/C Optimizing Compiler”的版本信息说明 MSVC 环境正常。注意普通 CMD 里直接敲cl是不行的必须先加载 vcvars64.bat 环境脚本这个后面会专门讲。2.2 OSGeo4W 依赖包少踩坑的安装方法从 OSGeo4W 或 QGIS 官网下载 osgeo4w-setup.exe建议下载 64 位版本。运行后选择“Advanced Install”安装目录我建议设为C:\OSGeo4W64不要用中文路径也不要有空格这是给后续 CMake 省事。包选择是重点。最省心的方式是在搜索框里搜 qgis勾选qgis-rel-dev这个包它会自动拉入一整套编译依赖。如果你更愿意手动控制至少要确认以下几类包被选中GIS 核心库gdal、gdal-devel、geos、geos-devel、proj、proj-develQt 相关qt5-qtbase、qt5-qtsvg、qt5-qttools 以及对应的 -devel 包辅助库qca-qt5、qca-qt5-devel、qscintilla-qt5-devel、qwt-qt5-devel基础库libzip、libzip-devel、zlib、zlib-devel、expat、expat-devel、sqlite3、sqlite3-devel网络与数据库openssl-devel、libcurl-devel、libpq-devel、libxml2-devel看到带-devel的包就尽量勾上devel 代表开发头文件和导入库编译必需。整个下载安装过程会拉几百 MB 的文件取决于网速大概十几分钟到半小时。装完以后C:\OSGeo4W64\include和C:\OSGeo4W64\lib里就有编译 QGIS 需要的全部头文件和导入库了。2.3 Python / CMake / Ninja / Qt 的版本核对Python 我建议直接用 OSGeo4W 环境里安装的版本。安装 OSGeo4W 时确认勾选python3-core和python3-devel装完会在C:\OSGeo4W64\apps\Python310之类的目录下出现 Python 解释器。用它的最大好处是sip 和 PyQt5 的头文件、库都由 OSGeo4W 统一提供和 Python 编译器的版本天然配套CMake 也不用额外折腾路径。如果你更习惯用 python.org 的独立 Python也可以但那样就要自己 pip 安装 PyQt5 和 sip并且需要显式把 PYTHON_INCLUDE_DIR、PYTHON_LIBRARY 传给 CMake多一层工作量第一遍编译不建议这么做。CMake 和 Ninja 直接下载官方 Windows 安装包。CMake 安装时勾选“Add CMake to the system PATH”Ninja 解压到C:\Tools\ninja后把该目录加到系统 PATH。检查环境cmake --version ninja --version python --version qmake -vqmake 来自 OSGeo4W 的 Qt5命令位于C:\OSGeo4W64\bin\qmake.exe。如果 qmake 输出版本是 5.15.x环境就算齐了。3. 源码获取与 CMake 配置3.1 源码下载与目录规划QGIS 的源码从 GitHub 上获取选 3.34.10 对应的 tag分支名是final-3_34_10。可以用 git clone 指定分支也可以直接下载对应发布版的 zip 包两者本质一样。我推荐的目录结构是C:\src\qgis-3.34.10 源码目录 C:\build\qgis-3.34.10-build 构建目录out-of-source C:\OSGeo4W64 依赖库目录 C:\QGIS-3.34.10-install 最终安装目录构建目录一定要放在源码目录外。QGIS 的 CMake 虽然允许 in-source 构建但会污染源码树后续增量编译和 git 操作都很痛苦。还有一点很重要所有路径都别用中文和空格。CMake 和 MSVC 对带空格的路径处理时好时坏遇到诡异报错很难排查不如最开始就绕开。磁盘空间预留 30GB 以上其实纯构建产物大约 10GB但各种缓存、中间文件和安装副本很容易超预期。3.2 初始化命令行环境编译 QGIS 需要在命令行完成环境初始化顺序有讲究。打开 CMD先加载 MSVC 环境再把 OSGeo4W、CMake、Ninja 的路径追加到 PATHcall C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat set PATHC:\OSGeo4W64\bin;%PATH% set PATHC:\OSGeo4W64\apps\Python310;%PATH% set PATHC:\Program Files\CMake\bin;C:\Tools\ninja;%PATH%如果你用的是 VS2022vcvars64.bat 路径改为C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat。为什么先执行 vcvars64.bat因为它会设置 cl.exe、rc.exe、link.exe 等一大堆 MSVC 工具链的环境变量如果 PATH 里先混入了 OSGeo4W 自带的工具有可能发生工具冲突。先把 MSVC 环境固化下来再追加其他路径最稳。3.3 CMake 参数逐项解析与实测配置在源码根目录下执行 CMake 配置。以下是我验证过的完整命令行cmake -S C:/src/qgis-3.34.10 -B C:/build/qgis-3.34.10-build -G Ninja ^ -DCMAKE_BUILD_TYPERelease ^ -DCMAKE_INSTALL_PREFIXC:/QGIS-3.34.10-install ^ -DCMAKE_PREFIX_PATHC:/OSGeo4W64;C:/OSGeo4W64/apps/Qt5 ^ -DCMAKE_INCLUDE_PATHC:/OSGeo4W64/include ^ -DCMAKE_LIBRARY_PATHC:/OSGeo4W64/lib ^ -DPYTHON_EXECUTABLEC:/OSGeo4W64/apps/Python310/python.exe ^ -DWITH_BINDINGSON ^ -DWITH_3DON ^ -DWITH_GRASSOFF ^ -DWITH_SERVEROFF ^ -DENABLE_TESTSOFF ^ -DWITH_APIDOCOFF逐项说明这些参数为什么这样设CMAKE_BUILD_TYPERelease编译优化后的发行版QGIS 官方包也是 Release。Debug 版可以编译但你跑起来会明显感觉卡而且体积巨大。CMAKE_INSTALL_PREFIX最终 install 的安装目录建议和源码、构建目录分开。CMAKE_PREFIX_PATH告诉 CMake 去哪儿找依赖。这里同时包含 OSGeo4W 根目录和 Qt5 所在目录两个路径都不能省。CMAKE_INCLUDE_PATH和CMAKE_LIBRARY_PATHOSGeo4W 的头文件和库目录不是标准布局CMake 有时搜不到显式指定最保险。PYTHON_EXECUTABLE指向 OSGeo4W 的 Python保证 Python 绑定和 PyQt5/sip 出自同一套环境。WITH_BINDINGSON开启 Python 绑定也就是 PyQGIS。如果你不需要 Python 插件可以 OFF但建议 ONQGIS 很多实用功能依赖 Python。WITH_3DONQGIS 3D 视图功能依赖 Qt3DOSGeo4W 有对应库。如果编译报 Qt3D 找不到可以改成 OFF。WITH_GRASSOFFGRASS 插件依赖的系统库太多源码编译极其容易栽跟头。非 GIS 重型用户建议直接关掉。WITH_SERVEROFFQGIS Server 是服务端组件桌面开发不需要就先关能减少不少编译时间。ENABLE_TESTSOFF跳过测试目标编译速度快很多。WITH_APIDOCOFF不生成 API 文档省时省力。如果 CMake 配置完成后没有报错就会生成build.ninja文件。这一步如果报缺库缺头文件绝大多数是 CMAKE_PREFIX_PATH 或 LIBRARY_PATH 没写对回到 2.2 核对包是否装全。还有一个细节如果机器上同时装了 Qt6CMake 有可能误找到 Qt6 的包导致配置失败。这时在 CMake 参数里加一行-DQT_VERSION_MAJOR5强制锁定 Qt5能省去很多麻烦。4. 编译执行与产出物说明4.1 触发构建Ninja 与并行参数配置成功后执行编译cmake --build C:/build/qgis-3.34.10-build --parallel 8--parallel后面的数字是并行编译任务数建议设为物理核心数或稍小一点。我的机器是 8 核 16 线程设置 8 或 10 都稳定。如果内存只有 16GB尽量别超过 8否则每个编译进程吃几百 MB 内存内存不够会触发 OOM反而更慢。首次完整编译时间大致如下机器配置预计耗时8 核 / 16GB 内存 / SSD1.5 ~ 2 小时16 核 / 32GB 内存 / SSD30 ~ 45 分钟8 核 / 16GB 内存 / 机械硬盘3 小时以上编译期间控制台会不断刷[xxx/xxxx] Building CXX object ...的进度信息Ninja 还会显示当前构建的百分比。不要因为很久没动 QQ 消息就以为卡死了编译 QGIS 大文件时单个目标几十秒都正常。4.2 常用构建目标与增量编译开发过程中没必要每次都全量编译。QGIS 的构建系统里几个常用目标分别是cmake --build C:/build/qgis-3.34.10-build --target qgis_core cmake --build C:/build/qgis-3.34.10-build --target qgis_app cmake --build C:/build/qgis-3.34.10-build --target qgisqgis_core核心库也就是qgis_core.lib和qgis_core.dllQGIS 最底层的数据模型、地图渲染、空间分析都在这。qgis_app应用程序层包含主窗口和交互逻辑产物是qgis_app.lib。qgis最终可执行目标生成qgis.exe。Ninja 的增量编译做得很好修改某个源文件后再次执行 build它只会重新编译受影响的翻译单元链接时也复用已有的 .obj 文件。我实测修改一个核心文件后增量编译只需要几分钟这对迭代开发非常重要。4.3 运行、安装与部署编译完成后可执行文件的位置取决于生成器。因为用的是 Ninja单配置生成器qgis.exe 生成在C:\build\qgis-3.34.10-build\output\bin\qgis.exe开发环境里直接运行会遇到 DLL 找不到的问题需要把 Qt 和 OSGeo4W 的 bin 目录加进 PATHset PATHC:\build\qgis-3.34.10-build\output\bin;%PATH% set PATHC:\OSGeo4W64\bin;%PATH% qgis.exe如果准备把编译产物安装到独立目录cmake --install C:/build/qgis-3.34.10-build执行完以后C 盘 QGIS-3.34.10-install 目录下会有完整的 bin、lib、share、plugins 等目录。运行安装版 qgis.exe 时还需要设置 QGIS_PREFIX_PATH 环境变量指向安装目录否则程序找不到插件和资源文件set QGIS_PREFIX_PATHC:\QGIS-3.34.10-install C:\QGIS-3.34.10-install\bin\qgis.exe真正要把这个编译结果部署到别的机器上推荐两种方式。一种是直接把整个安装目录拷贝过去同时确保目标机器有对应版本的 Visual C 运行库、OSGeo4W 运行库和 Qt 运行库。另一种是用 windeployqt 自动收集 Qt 依赖再手动补充 GDAL、GEOS、PROJ 的 DLL。前者省事后者干净看你是自己用还是发给其他人。5. 常见问题与排查技巧实录5.1 高频报错速查表编译 QGIS 的报错看起来千奇百怪但排掉表象后其实都是几个原因。我整理了一份高频速查表报错信息原因处理方法Could not find a package configuration file provided by Qt5CMake 找不到 Qt5 的 cmake 配置检查 CMAKE_PREFIX_PATH 是否包含 C:/OSGeo4W64/apps/Qt5或显式 -DQt5_DIRCould NOT find GDAL (missing: GDAL_INCLUDE_DIR)OSGeo4W 头文件路径没传给 CMake确认 gdal-devel 已装检查 CMAKE_INCLUDE_PATHNo such file or directory: sip.hPython 绑定需要 sip 头文件确认 python3-devel 和 python3-sip 已安装或关闭 WITH_BINDINGSninja: error: loading build.ninjaCMake 配置失败或未完成先回看 CMake 输出信息修正参数后重新执行 cmake -SLNK1104: cannot open file qgis_core.lib链接时核心库还没生成先编译 qgis_core 目标再编译 qgis_app/qgisProgram cant start because Qt5Core.dll is missing运行时找不到 Qt DLL把 C:/OSGeo4W64/bin 加入 PATHqgis.exe 闪退但控制台无输出DLL 版本混用或插件目录异常检查 PATH 中是否存在多处 Qt统一为 OSGeo4W 的 Qt5.2 新手最容易踩的四个坑先说第一个坑Qt 和 OSGeo4W 混用。OSGeo4W 的 bin 目录里有一套 Qt 运行库如果你又在系统里装了官方 Qt 5.15并且 PATH 顺序不对qgis.exe 启动时会加载到错误的 DLL表现就是闪退没有任何提示或者在启动日志里报一堆奇怪的 symbol 错误。解决办法就是统一来源全部用 OSGeo4W 的 Qt或者全部用官方 Qt QGIS-DEPS 依赖两者不要混。第二个坑是 Python 绑定版本不一致。如果你的 WITH_BINDINGS 打开了但 Python 用的是 python.org 版本而 PyQt5/sip 来自 OSGeo4W编译阶段可能侥幸通过运行时导入 qgis 库十有八九报ModuleNotFoundError或 sip 版本不匹配。如果你不想用 OSGeo4W 的 Python就老老实实pip install PyQt55.15.* sip并把 CMake 的 PYTHON_LIBRARY 显式指过去。第三个坑是 CMake 缓存残留。我第一次配置时 CMAKE_INCLUDE_PATH 写错了编译报找不到 gdal.h改掉后重新执行 CMake 配置但忘了缓存里还有旧路径。结果是新的找不到和旧的残留共存反复报错非常崩溃。遇到依赖路径变化的情况直接把 build 目录删掉重新配置反而比来回试参数更快。删一个目录不过几分钟浪费半小时排查缓存问题才是真亏。第四个坑和杀毒软件有关。Windows Defender 实时扫描在编译大量小文件时会造成巨大性能损耗我试过把 build 目录加入排除列表后编译时间直接缩短三分之一。如果编译过程中发现 CPU 占用忽高忽低但进度很慢可以检查一下是不是杀毒软件在做文件扫描。5.3 编译完成后的功能验证清单编译成功不意味着万事大吉我习惯按下面的清单逐一验证启动 qgis.exe能正常显示主窗口没有闪退。菜单“帮助 - 关于 QGIS”里显示的版本号是 3.34.10且“已安装的库”里能看到自己编译时间相关的信息。拖入一个本地 shapefile 或 GeoPackage 文件地图画布能正常显示要素。打开 Python 控制台输入import qgis.core没有报错。加载一个 XYZ 瓦片底图比如 OpenStreetMap确认网络、Qt 网络模块、栅格渲染链路正常。随手跑一个“重投影”或“裁剪”算法确认 GDAL、PROJ 库工作正常。前两项能过说明核心编译成功Python 那项能过说明绑定没有问题后两项能过说明依赖库在运行时都配对上了。如果最后发现地图渲染时某些图标缺失或者工具按钮异常大概率是资源文件路径没找到先检查 QGIS_PREFIX_PATH 是否设置正确而不是怀疑编译有问题。我个人在实际操作中的体会是QGIS 源码编译在 Windows 上并不神秘本质就是依赖版本统一、路径不要有中文或空格、缓存出问题果断重置这三件事。如果你首次配置 CMake 报错沉住气把报错信息里提到的库名和“missing”放一起搜多半是某个 -devel 包没装。最后再分享一个小技巧编译过程中如果想暂时退出直接关掉 CMD 窗口即可Ninja 会把已经完成的编译结果存在 build 目录里下次重新跑同一条 build 命令它会自动跳过未变更的源文件继续从断点前进。这个特性在你需要反复调整源码时特别友好。