编译好的QGIS工程文件：从依赖配置到功能定制与二次开发

简介这是一套基于QGIS源码编译生成的完整工程文件面向需要二次开发或定制GIS功能的开发者。项目通过CMake与Visual Studio 2019编译并集成Qt 5.15.2环境亲测可正常打开运行。工程内含有常用的GIS模块用户可根据实际需求自行增加、删除或修改对应模块灵活性较高。资源包共8183个文件约473MB涵盖svg矢量图标、头文件、Python脚本、DLL动态库、PNG图像以及QGIS特有的qgm工程文件等结构完整能支撑从界面到核心算法的二次开发。目前已有1210人浏览学习。下载后无需再手动配置第三方依赖和解决编译报错直接打开工程文件即可启动特别适合希望快速进入QGIS源码层进行功能扩展或学习编译流程的开发者能极大节省环境搭建与排错时间。1. 拿到编译好的QGIS工程文件它不只是安装包而是一个能改的起点先纠正一个预期编译好的QGIS工程文件重点不是“安装”而是“工程”。它通常是一套带着 CMakeLists.txt 或 Qt Creator 工程文件的源码目录外加已经跑通配置的构建目录。你能在 Qt Creator 里打开它、改某个功能模块、重新编译出带自己定制逻辑的 QGIS而这在装好的官方安装包里几乎是不可行的。它适合四类人需要把 QGIS 嵌进自己产品里的集成工程师、要裁剪体积或功能的交付团队、想在离线环境把依赖一次配齐的部署人员以及准备做二次开发的插件作者。先说清楚这个方向值不值得投入如果只是画地图安装包更快但当你需要“自家的 QGIS”这份工程文件才是真正的地下室。2. 拆开编译好的QGIS工程文件先从模块归属和目录结构建立认知很多人在 Qt Creator 里一打开工程就急着点构建结果几分钟后被满屏的 include 错误拍回桌面。我一般建议先花 20 分钟把目录结构走一遍搞清楚哪些功能模块在哪个子工程里后面编译和裁剪都会顺很多。2.1 目录地图src/core、src/gui、src/app 各管什么这份编译好的 QGIS 工程文件目录布局通常沿用官方源码组织方式。核心模块分三层顺序依赖很清楚目录对应库职责常见代码入口src/coreqgis_core不依赖界面的底线能力QgsProject、QgsVectorLayer、QgsExpression、QgsCoordinateReferenceSystemsrc/guiqgis_gui依赖 Qt Widgets 的绘图与交互QgsMapCanvas、QgsMapTool、图层树、属性表控件src/appqgis_app主程序菜单、工具栏、命令行分发main.cpp、QgisApp、QgisAppPluginManager注意依赖方向永远是从上往下src/gui依赖src/coresrc/app又依赖前两者。你如果只想把 QGIS 的地图引擎嵌进自己的桌面应用完全可以只编译qgis_core和qgis_gui手动把它们当成两套动态库链接进来。很多“把 QGIS 当 SDK 用”的工程项目文件里根本没有src/app这个子目录。除了这三层还有两个你迟早会碰到的目录python/放的是 Python 绑定相关代码plugins/是各类 C 插件比如处理 GDB 的ogr提供者插件、几何图形插件 GeometryShapes。这份工程文件的“基本功能模块”在我经手的项目里基本指矢量编辑、属性表、表达式引擎、地图画布、工程保存与恢复、OGR/GDAL 数据打开能力、坐标系转换。这些正好对应src/core和src/gui的大部分编译目标。2.2 功能模块放在哪应用内置和插件式加载是两回事我在指导新人时发现一个普遍的误解以为功能模块都以插件形式加载。实际上 QGIS 功能模块分两种组织形态各有千秋一种是“编译进主程序”的模块比如矢量编辑、字段计算器、表达式公式设置界面。这类模块写在src/app或直接作为qgis_gui的类存在编译后就在 EXE 里你在分发时不用额外带文件。代价是任何改动都要重新编译主程序编译时间通常以小时计。另一种是“插件式模块”比如数据源提供者、 GeometryShapes 这类几何工具插件。它们被编译成独立的 DLL 或.so文件运行时从插件目录动态加载。好处是修改一个插件只需要编译对应小工程分发时也灵活。坑在于运行时的插件搜索路径非常敏感编译出来加载不到基本模块一半原因是插件目录路径写错另一半是依赖库没打完。判断一个功能模块属于哪种方式有个笨办法在 Qt Creator 里打开函数定义如果代码在src/app或src/gui里直接能看到那就是内置如果只看到接口声明具体实现在plugins/子目录里那就是插件式。比如 FileGDB 的读取能力对外的接口在src/core/providers/ogr/而真正调用 ESRI 库的逻辑在src/providers/ogr里这幅编译好的工程文件会把这些边界画得很清楚。2.3 在 Qt Creator 里拉起工程的最小配置清单拿到工程文件后不要急着 Configure先确认三件事Qt 版本是否匹配、CMake 工具链是否是工程锁定的那套、第三方依赖目录是否还在原路径。我用一份典型的 Windows 工程配置命令来说明参数意义这段脚本假设你已经装好 Qt 和依赖库cmake -S . -B build-qtcreator ^ -DCMAKE_PREFIX_PATHC:/Qt/5.15.2/msvc2019_64;C:/deps ^ -DCMAKE_BUILD_TYPERelease ^ -DCMAKE_CXX_COMPILERcl ^ -DQGIS_CUSTOM_QT_INCLUDEC:/Qt/5.15.2/msvc2019_64/include ^ -DWITH_APPON ^ -DWITH_COREON ^ -DWITH_GUION cmake --build build-qtcreator --config Release --parallel 8说明一下参数CMAKE_PREFIX_PATH是告诉 CMake 去哪里找 Qt 和第三方库路径里包含 Qt 的 CMake 配置目录和依赖库根目录这是整个配置过程最容易出错的点CMAKE_BUILD_TYPERelease决定优化级别调试阶段可以换 Debug但注意 Debug 和 Release 的依赖库混用会导致链接失败WITH_APP/CORE/GUI是功能模块开关想简化工程就关掉 APP保留 CORE 和 GUI 嵌入自己程序。如果工程文件是 Qt Creator 的.pro工程你需要打开.pro文件确认QT core gui widgets和CONFIG c17这些基本信息然后指定构建目录与 Qt Kit。同一个源码目录在区分 Debug 和 Release 时我的习惯是建build-debug、build-release两个目录避免 CMake 缓存互相污染。3. 把依赖环境理顺Windows 和 Linux 编译前的两套处理路径很多编译好的 QGIS 工程文件拿回来第一眼看上去没问题但一编译就报cannot find -lxxx。这基本不是工程文件的问题而是依赖库的搜索路径没有交代清楚。编译 QGIS 不是编译一个普通的小工具它的依赖分三层Qt 基础、地理数据底层库、以及可选功能模块的第三方库。3.1 依赖分组没有 GDAL/PROJ 这套底层core 模块根本编译不过我按依赖的必要程度把它们分成三组这套分组也适用于判断工程文件是否完整第一组是必要依赖包括 QtCore、Gui、Widgets、Xml、Sql、GDAL/OGR 数据访问库、PROJ 坐标系库。没有 GDALQgsVectorLayer连 Shapefile 都打不开没有 PROJ坐标系变换模块直接报错。第二组是常用功能依赖包括 GEOS空间几何运算、SQLite空间索引和属性数据库、ExpatXML 解析。第三组是可选功能依赖比如 PostgreSQL 驱动、MDAL 洪水模型库、NetCDF这些没装也能编过只是对应功能模块会被禁用。在 Linux 上检查依赖最直接的办法是用发行版包管理一起装上比如在 Ubuntu 里常用的安装命令是sudo apt install qtbase5-dev qt5-qmake qttools5-dev-tools \ libqt5svg5-dev libqt5sql5-mysql libqt5xmlpatterns5-dev \ libgdal-dev libproj-dev libgeos-dev libsqlite3-dev命令里的每组包名按依赖分组对应qtbase5-dev提供 Qt 核心库libgdal-dev和libproj-dev提供地理数据底层能力libgeos-dev提供空间运算几何内核。注意版本匹配问题GDAL 和 PROJ 各有自己的主版本号QGIS 某版本对它们的 API 版本有硬性要求如果系统源里的版本太新或太旧编译时会出现函数签名对不上的情况我的排查顺序是先看工程根目录CMakeLists.txt里的最低版本提示而不是盲目升级依赖库。3.2 Windows 下编译MSVC 编译器和 Qt 目录是命门Windows 上最常见的翻车点是“编译器不匹配”。这份工程文件如果是在 MSVC 环境下生成的你强行用 MinGW 编译器打开链接阶段会报大量无法解析的外部符号因为 Qt 库本身是按 MSVC ABI 编译的两种编译器的二进制互不兼容。我常用的 Windows 编译姿势是先设置一个环境变量脚本把 Qt 和依赖库路径固定住再跑 CMakeset PATHC:/Qt/5.15.2/msvc2019_64/bin;C:/deps/bin;%PATH% set QTDIRC:/Qt/5.15.2/msvc2019_64 cmake -S . -B build-msvc ^ -DCMAKE_PREFIX_PATHC:/Qt/5.15.2/msvc2019_64;C:/deps ^ -DCMAKE_GENERATORVisual Studio 16 2019 -A x64 ^ -DWITH_BINDINGSOFF cmake --build build-msvc --config Release --parallel %NUMBER_OF_PROCESSORS%参数解释-DWITH_BINDINGSOFF表示不编译 Python 绑定如果目标只是跑通桌面程序和 C 开发关掉它能省掉一长串 SIP/PyQt 依赖生成器选 Visual Studio 与工程文件头里声明的 Qt 版本对应-A x64指定 64 位架构。编译结束后运行 GOST 目录下的qgis.exe如果提示找不到 Qt DLL原因就是 PATH 环境变量没有带上 Qt 的 bin 目录。3.3 Linux 下编译用系统 Qt 还是手动装 Qt 的取舍Linux 编译 QGIS 工程文件通常会遇到两个分支用发行版自带 Qt或手动安装 Qt 离线包。用系统 Qt 的好处是依赖完整apt install一条龙把 GDAL、PROJ、GEOS 全装完生成 Makefile 简单缺点是 Qt 版本被发行版锁定如果 QGIS 要求 Qt 5.15 而系统源里只有 5.14CMake 配置阶段就会失败。我的处理方法是先用快速命令探测系统 Qt 版本低于要求的版本就走手动安装。qmake -v cmake -S . -B build-linux \ -DCMAKE_PREFIX_PATH/opt/Qt/5.15.2/gcc_64 \ -DCMAKE_BUILD_TYPERelease \ -DGDAL_CONFIG/usr/bin/gdal-config \ -DPROJ_INCLUDE_DIR/usr/include \ -DPROJ_LIBRARY/usr/lib/x86_64-linux-gnu/libproj.so cmake --build build-linux --parallel 4解释一下qmake -v用来快速判断 Qt 版本是否够用GDAL_CONFIG是 QGIS 工程查询 GDAL 安装位置的依赖工具如果这个路径不对CMake 会提示找不到 GDALPROJ_INCLUDE_DIR和PROJ_LIBRARY是手动指定头文件和静态库路径的方式适合自动检测失败时写死。这里把 Release 加上后Linux 的编译通常需要 40 分钟到 1 小时取决于机器核数建议第一次编译就用-j4限制并发数别把机器拖到没响应。4. 增删功能模块把一份标准 QGIS 改成你自己的定制版工程文件的价值不在“能编过”而在“能改”。基本功能模块齐全之后紧接着要考虑的是怎么按业务需求裁剪或增加。我在这里给出三套具体操作按“加模块—减模块—加自定义逻辑”的顺序展开。4.1 基本功能模块清单先确认你手里有哪些能力一份标准的 QGIS 功能模块清单在我接触到的工程文件里通常包含这些能力工程文件的创建、打开、保存与恢复矢量图层Shapefile、GeoJSON、GPKG的加载与编辑属性表的字段查看、字段值和表达式批量赋值栅格图层显示与基础配色地图坐标参考系的分配和转换空间书签、比例尺、图例的出图能力内置表达式引擎的基础函数库。这些模块的共同点是它们都挂在src/core或src/gui的主干上属于“基本功能”。如果你是嵌入式集成场景比如只做一个属性录入工具连出图和书签都可以去掉如果是测绘内业软件表达式引擎和属性表必须保留。建议你先在源码树里用查找功能搜索QgsExpression类在多少个文件被引用搜索数量越多说明表达式功能被绑得越紧想单独砍掉的代价越大。4.2 增加一个功能模块以自定义表达式函数为例这一节的实际操作我选择在表达式引擎里注册一个自定义函数这也是 QGIS 扩展里最入门但最常用的功能。它对应“矢量 表达式 公式 设置”这个检索词很多业务场景比如批量给字段赋值、按时间规整属性值都会用到这类自定义函数。以 C 方式在工程文件里加一个函数我最常写的模板是这样#include qgsexpression.h #include qgsexpressionfunction.h #include QDateTime static QVariant f_now_iso(const QgsExpressionFunction::Context ctx, const QVariantList values) { Q_UNUSED(ctx); Q_UNUSED(values); return QDateTime::currentDateTime().toString(Qt::ISODate); } void registerCustomFunctions() { QgsExpressionFunction* fn new QgsExpressionFunction( QStringLiteral(now_iso), // 函数名表达式中写 now_iso() 0, // 参数个数0 表示无参 f_now_iso, QStringLiteral(自定义函数), QStringLiteral(返回当前时刻的 ISO 8601 时间字符串) ); QgsExpression::registerFunction(fn); }这段代码里最关键的是QgsExpression::registerFunction(fn)它把函数注册进全局表达式引擎注册之后你在字段计算器里写now_iso()就能得到当前时刻的字符串。需要注意的点函数名不能和内置函数重名否则注册会失败且不报错参数个数声明为 0调用时括号不能省略如果用 Python 去调用这个 C 注册的函数需要清空表达式引擎缓存或重启程序才能生效。4.3 裁剪功能模块关闭 Python 绑定和分发包体积很多交付场景不需要 Python 控制台也不需要内置浏览器。这时候我一般会在 CMake 配置阶段直接关掉相关模块而不是去删源码文件。用开关裁剪的好处是万一以后要恢复功能重新打开开关编译即可不必回滚代码。cmake -S . -B build-mini ^ -DCMAKE_BUILD_TYPERelease ^ -DWITH_BINDINGSOFF ^ -DWITH_ANALYSISOFF ^ -DWITH_SERVEROFF ^ -DWITH_GRASSOFF ^ -DWITH_CUSTOM_WIDGETSOFF ^ -DWITH_QT5SERIALPORTOFF cmake --build build-mini --config Release --parallel 4每个开关对应一个明确的功能模块WITH_BINDINGS控制 Python 绑定关掉后不再生成 PyQGIS 模块WITH_SERVER控制 QGIS Server 的网页地图服务能力桌面端通常用不到WITH_GRASS是 GRASS GIS 集成接口属于较大且独立的重量级模块WITH_ANALYSIS是空间分析算法库。这些开关关掉之后编译产物里的库文件会少几个需要分发的目录也干净很多。但注意不要关掉WITH_CORE或WITH_GUI那是主程序的基础关掉后整个界面都拉不起来。5. 避坑编译好的QGIS工程文件最常见的5个翻车现场这一章全部来自我自己的编译血泪经验按“现象—原因—解决”的方式写。遇到问题先对照现象不要急着重装依赖多半是路径或 ABI 的问题。5.1 现象CMake 配置时报错找不到 Qt5明明 Qt 已经装了我最早编译 QGIS 时遇到过这个玄学问题Qt 明明装在C:/Qt/5.15.2CMake 始终坚持找不到。原因基本只有一个CMAKE_PREFIX_PATH没有指到 Qt 的编译器特定目录比如 Qt 安装在 MSVC 环境就必须写C:/Qt/5.15.2/msvc2019_64而不是C:/Qt/5.15.2。解决方法是把qt5-config.cmake所在目录写进前缀路径也可以用-DQt5_DIR...直接指到库的lib/cmake/Qt5子目录我在只装了一套 Qt 时都用后者逻辑更明确。5.2 现象编译进行到一半链接时报无法解析的外部符号这是一个非常具体的链接失败场景报错内容会指向某个类的方法比如QgsVectorLayer::addFeature。原因通常是工程文件里的头文件路径和库文件路径不一致或者混用了 Debug 和 Release 的 Qt 库。我遇到最多次的是 Qt 自带的Qt5Cored.lib和Qt5Core.lib混用。解决方法是检查 CMake 缓存里的CMAKE_IMPLICIT_LINK_DIRECTORIES和CMAKE_BUILD_TYPE是否一致Debug 工程必须让 Qt 依赖也走d后缀库不要手动往 PATH 里同时塞两个版本的 Qt 目录。5.3 现象编译成功但运行时报“无法加载地图数据源缺少 GDAL provider”这种报错往往是图源数据加载能力缺失不是 QGIS 主体的问题。原因在于 GDAL 本身是插件式驱动即使主程序编译成功如果gdalplugins目录没放到程序运行时搜索的路径下或者 GDAL 从源码编译时没开启特定驱动Shapefile 能打开但 GDB 打不开就是驱动的缺失。解决方法是先确认工程文件编译后产出的“插件目录”把C:/deps/bin/gdalplugins或源码里src/providers/ogr编译出的资源目录放进可执行文件旁的plugins下同时通过环境变量GDAL_DRIVER_PATH指向该目录。5.4 现象编译好的 QGIS 打开 GDBFile Geodatabase失败但官方安装包能打开这个问题在热词“qgis打开gdb”里很突出。很多企业手里有 ESRI File Geodatabase 数据官方安装包里默认带了 FileGDB 驱动而自己编译的工程文件默认不包含该驱动或仅包含 OpenFileGDB 只读驱动。原因在于 GDAL 的 FileGDB 读写驱动需要 ESRI SDK 或 GDAL 以特定选项编译。解决方法是检查gdalinfo --formats | grep -i gdb如果只有OpenFileGDB说明只能读要写回必须重新编译 GDAL 并启用 FileGDB 驱动同时将相关 DLL 一并打包进最终分发的插件目录。5.5 现象表达式计算器中字段和值下拉列表为空自定义函数注册后不生效有时表达式对话框能打开但“字段和值”面板里看不到当前图层字段写好的表达式批量赋值也总返回空。原因通常是该矢量图层没有正确加载到有效数据源或者表达式引擎的全局变量缓存未刷新。解决方法是先在图层属性里确认要素数量是否显示正常然后调用QgsExpression::cleanRegisteredFunctions()并重新注册如果字段列表为空八成是图层数据源 URL 未正确设置需要重新设置QgsVectorLayer的数据源字符串比如file:///D:/data/roads.shp?delimiter,xFieldlongitudeyFieldlatitude。6. 验证编译好的QGIS工程文件一个最小回归清单和部署习惯先说结论验证一个编译好的 QGIS 工程文件重点不是看它能不能打开窗口而是看核心模块是否真的可用。我每次交付前都固定跑一遍下面这套清单时间成本控制在 15 分钟以内。我习惯用命令行模式先做无界面冒烟测试确认 core 模块能起来./build/bin/qgis_process --help ./build/bin/qgis_process listqgis_process是 QGIS 3.x 里提供命令行工具的模块--help能输出信息说明 main 模块正常加载list能列出注册的各类算法模块。如果提示找不到库优先检查 LD_LIBRARY_PATH 或 Windows 的 PATH 是否包含了构建目录下的库目录。接着用一段最小 PyQGIS 脚本验证数据模块和表达式模块from qgis.core import * QgsApplication.setPrefixPath(build/bin, True) QgsApplication.initQgis() layer QgsVectorLayer(D:/data/roads.shp, roads, ogr) print(valid:, layer.isValid()) print(count:, layer.featureCount()) expr QgsExpression(length(geometry(layer))) print(expr ok:, expr.hasEvalError()) QgsApplication.exitQgis()脚本里的setPrefixPath是指向 QGIS 安装目录如果编译出的库在build/bin就写这个相对路径QgsVectorLayer的第三个参数ogr指定驱动名测试时能同时验证 GDAL 驱动是否找齐QgsExpression构造时可以顺手用hasEvalError()判断表达式引擎有没有初始化错误。最后再说一个我自己的习惯我通常在打包前重新用 Release 配置完整编译一次然后清空build-debug目录避免把调试符号和发布库混在一起。清空构建目录听起来有点冒险但这正是避免“编译期正常、运行为零”混乱的后悔药。前面提到的表达式注册函数、裁剪开关、插件路径我全部会整理成一个 README 放在工程目录里下次维护时不用翻旧笔记。希望这份从编译到验证的路径能帮到你。本文还有配套的精品资源点击获取