1. 为什么值得折腾QGC二次开发QGC地面站QGroundControl在无人机圈子里基本是绕不开的工具。不管你是飞PX4还是ArduPilot固件QGC都是最主流的航线规划、参数调试、固件烧录平台。但很多人用着用着就会发现官方版本虽然稳定可总有些地方不趁手——比如想加一个自定义的遥测数据面板、想改一下航线规划的逻辑、想接入自己公司的私有协议这时候就不得不走上二次开发这条路。我自己第一次编译QGC的时候踩了不少坑。网上教程要么太老要么跳步严重要么默认你已经是个Qt老手。实际上一个做飞控算法的工程师和一个做前端出身的开发者面对QGC源码时的困惑点完全不同。这篇内容就是把我自己从零编译QGC的完整过程拆开来讲包括环境怎么搭、源码怎么拉、Qt Creator怎么配、编译报错怎么查以及那些教程里不会写的坑。适合谁看如果你已经会用QGC地面站的基本功能想改点东西但不知道从哪下手或者你是嵌入式/飞控方向的学生课程项目需要定制一个地面站再或者你只是好奇QGC内部长什么样想编译一份自己玩玩——这篇都能给你一条能走通的路。不需要你是Qt专家但至少得知道C的基本语法和命令行怎么用。QGC的代码量不小整个工程编译下来中间文件加上最终产物轻松吃掉几十个G的磁盘空间。所以开始之前先确认你的机器至少有100G以上的空闲空间内存建议16G起步8G也能编但会很痛苦。操作系统方面Windows和Ubuntu都可以我下面会以Ubuntu为主来写因为QGC在Linux下的编译体验明显更顺依赖管理也简单得多。Windows下不是不能编但光是Qt版本和编译器版本的匹配就够你喝一壶的。2. 编译前的环境准备与工具选型2.1 操作系统与硬件的最低要求先说清楚硬件和系统的底线免得你编到一半发现机器扛不住。QGC的源码仓库拉下来大概2到3个G但编译过程中产生的中间文件会膨胀到20G以上如果开了调试符号30G也正常。所以磁盘空间我给的建议是至少预留80G最好100G以上。内存方面链接阶段是吃内存大户16G是比较舒服的配置8G的话建议把并行编译的线程数降下来不然容易卡死。操作系统我推荐Ubuntu 20.04或者22.04这两个版本我都实际编过依赖库的版本比较合适。Ubuntu 18.04也能用但有些库的版本偏老需要手动升级。Windows 10/11也可以但你需要装Visual Studio 2019或者2022再加上Qt Creator整个工具链的配置复杂度比Linux高不少。如果你是第一次编译QGC我强烈建议先在Ubuntu下走通一遍理解了整个流程之后再考虑在Windows下折腾。注意不要用太新的Ubuntu版本比如刚发布的非LTS版本Qt的某些依赖可能还没跟上会出现一些莫名其妙的链接错误。2.2 Qt版本的选择与安装QGC对Qt版本是有明确要求的。不同版本的QGC源码对应的Qt版本不一样这个必须匹配否则编译必挂。一般来说QGC 4.2以上的版本需要Qt 5.15.2或者Qt 6.5以上的版本。我个人的建议是先去QGC的官方GitHub仓库看一下你准备编译的那个分支的README或者CI配置文件里面会写清楚需要的Qt版本。安装Qt的时候不要用系统自带的apt版本那个版本通常缺少QGC需要的某些模块。正确的做法是去Qt官网下载在线安装器选择自定义安装勾选以下组件Qt 5.15.2或者你需要的版本下的Desktop gcc 64-bitQt ChartsQt Quick Controls 2Qt LocationQt MultimediaQt Serial PortQt SVGQt Network Authorization这些模块缺一不可特别是Qt Location和Qt ChartsQGC的地图和仪表盘都依赖它们。安装路径建议用默认的不要带空格和中文不然后面配置Kit的时候容易出问题。2.3 编译工具链与依赖库Ubuntu下需要安装的基础工具包括build-essential、cmake、git、ninja-build。其中ninja-build是我强烈推荐的它比make快很多特别是在多核机器上。安装命令很简单sudo apt update sudo apt install build-essential cmake git ninja-build除了这些基础工具QGC还依赖一些系统库比如libssl-dev、libasound2-dev、libudev-dev、libsdl2-dev等。这些库如果不装编译到一半就会报找不到头文件的错误。我建议一次性把这些都装上sudo apt install libssl-dev libasound2-dev libudev-dev libsdl2-dev libxcb-xinerama0-dev还有一个容易漏掉的是GStreamer相关的库QGC的视频流功能依赖它。如果你不需要视频功能可以在编译时关掉但默认是开的所以还是装上比较省事sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev2.4 源码获取与分支选择QGC的源码托管在GitHub上直接clone就行。但要注意不要直接clone master分支master分支是开发版可能随时处于不可编译的状态。如果你只是想稳定使用建议checkout到最新的稳定tag。比如git clone https://github.com/mavlink/qgroundcontrol.git cd qgroundcontrol git checkout v4.2.8分支的选择取决于你的需求。如果你要跟着PX4的最新固件走那就用比较新的稳定版如果你要兼容老版本的ArduPilot可能需要用旧一点的QGC版本。我个人的经验是QGC 4.2.x系列比较成熟社区资料也多适合入门。拉源码的时候还有一个坑submodule。QGC依赖一些第三方库作为submodule如果你clone的时候没有加--recursive参数后面编译会报缺文件。补救方法是git submodule update --init --recursive这一步会下载不少东西网络不好的话可能要等一会儿。如果中途断了重新执行一次就行git会接着下载。3. Qt Creator的配置与工程加载3.1 Qt Creator的安装与Kit配置Qt Creator在你安装Qt的时候会一起装上不需要单独下载。打开Qt Creator之后第一件事是检查Kit配置。所谓Kit就是Qt Creator用来编译工程的一套工具组合包括编译器、Qt版本、调试器等。进入Tools - Options - Kits你应该能看到一个自动检测到的Desktop Kit。点进去检查几个关键项Compiler应该是GCC 64bitQt version应该是你安装的Qt 5.15.2Debugger应该是系统的gdb。如果Qt version那一栏是空的或者显示错误说明Qt Creator没有自动检测到你的Qt安装路径需要手动添加。手动添加的方法是在Qt Versions标签页里点Add然后找到你Qt安装目录下的qmake可执行文件。比如~/Qt/5.15.2/gcc_64/bin/qmake。添加完之后回到Kits页面把Qt version选成你刚添加的这个。提示如果你在Ubuntu下用apt装了qtcreator它可能会用系统自带的Qt版本和你手动安装的Qt冲突。建议直接用Qt官方安装器里的Qt Creator避免版本混乱。3.2 打开QGC工程与首次配置在Qt Creator里选择File - Open File or Project然后找到QGC源码根目录下的qgroundcontrol.pro文件。Qt Creator会问你用哪个Kit来配置这个工程选你刚才配好的Desktop Kit就行。首次打开工程的时候Qt Creator会解析整个.pro文件这个过程可能需要几分钟因为QGC的工程结构比较复杂有很多子项目和条件编译。解析完成之后你会看到左侧的项目树里有很多子项目比如libs、src、test等。在正式编译之前还需要做一件事配置构建目录。默认情况下Qt Creator会在源码目录旁边创建一个build目录这个没问题。但如果你之前编译过建议先清理一下避免旧的中间文件干扰。Build - Clean All然后再Build - Run qmake最后再Build - Build All。3.3 编译参数的调整与优化QGC默认的编译配置是Debug模式这个模式编译出来的程序体积大、运行慢但调试方便。如果你只是想跑起来看看建议切换到Release模式。在Qt Creator左下角的构建套件选择器那里点一下选择Release。Release模式下编译时间会短一些但链接阶段仍然很吃资源。如果你机器核多可以在.pro文件或者Qt Creator的构建设置里加上-j8或者更高的并行数。不过要注意并行数太高可能导致内存不够特别是链接的时候。我一般用-j4或者-j6比较稳。还有一个编译选项是CONFIGdebug和CONFIGrelease这两个不要同时加会冲突。另外如果你不需要单元测试可以在.pro文件里把test子项目注释掉能省不少编译时间。4. 编译过程中的常见报错与排查4.1 依赖库缺失导致的编译中断这是最常见的报错类型。症状是编译到某个文件时提示fatal error: xxx.h: No such file or directory。这种问题一般是因为系统缺少对应的开发库。解决办法是根据报错的头文件名反查它属于哪个库然后apt安装对应的-dev包。比如报错说找不到openssl/ssl.h那就是缺libssl-dev找不到alsa/asoundlib.h那就是缺libasound2-dev。我前面列的那些库基本覆盖了大部分情况但如果你开了额外的功能可能还需要装别的。有一个比较隐蔽的情况是库装了但版本不对。比如QGC需要OpenSSL 1.1但你的系统装的是OpenSSL 3.0这时候编译能过但运行时会报符号找不到。这种情况在Ubuntu 22.04上比较常见因为22.04默认的OpenSSL就是3.0。解决办法是手动编译一个OpenSSL 1.1放到工程里或者用QGC提供的脚本去下载预编译的版本。4.2 Qt模块找不到的解决方法另一种常见的报错是Unknown module(s) in QT: xxx。这说明你安装的Qt缺少某个模块。比如报错说Unknown module(s) in QT: location那就是你装Qt的时候没有勾选Qt Location模块。解决办法是重新运行Qt的在线安装器找到你安装的那个Qt版本把缺少的模块勾上。不需要卸载重装安装器会自动补上缺的模块。还有一种情况是模块装了但Qt Creator找不到。这时候检查一下Kit配置里的Qt version路径是否正确以及.pro文件里的QT 语句是否写对了。有时候QGC的.pro文件里会根据平台条件添加模块如果你在Windows下编译可能某些Linux特有的模块就不会被添加这是正常的。4.3 链接阶段的符号冲突与内存不足链接阶段最常遇到的两个问题是符号冲突和内存不足。符号冲突的表现是multiple definition of xxx或者undefined reference to xxx。前者通常是因为同一个符号在多个地方定义了后者是因为某个库没有链接进来。QGC的工程里有一些第三方库是静态链接的如果这些库之间有不兼容的符号就会报冲突。这种情况比较难排查一般需要看完整的链接命令找到冲突的符号来自哪个库然后调整链接顺序或者去掉重复的库。内存不足的表现是链接器被系统kill掉报错信息可能是collect2: fatal error: ld terminated with signal 9。这就是典型的OOMOut Of Memory。解决办法是降低并行编译数或者增加swap空间。我一般会临时加一个8G的swap文件sudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile编译完之后可以关掉不影响系统。4.4 编译成功但运行闪退的排查思路有时候编译能过但一运行就闪退或者界面出不来。这种情况一般是运行时依赖的问题。首先检查是不是缺动态库用ldd命令看一下可执行文件依赖的库有没有找不到的ldd ./QGroundControl | grep not found如果有not found的根据库名安装对应的包就行。另一个常见原因是Qt插件路径不对。QGC运行时需要加载Qt的平台插件比如libqxcb.so。如果Qt Creator的运行环境没有正确设置QT_PLUGIN_PATH就会报This application failed to start because no Qt platform plugin could be initialized。解决办法是在Qt Creator的Projects - Run - Environment里加上QT_PLUGIN_PATH/home/你的用户名/Qt/5.15.2/gcc_64/plugins或者直接在命令行里export这个变量再运行。5. 二次开发的切入点与实操建议5.1 从修改界面开始练手编译跑通之后下一步就是试着改点东西。我建议从界面入手因为QGC的界面是用QML写的改起来比较直观不容易搞崩核心逻辑。比如你可以试着改一下主界面的标题文字或者调整某个按钮的位置。QML文件主要在src/UI目录下比如MainWindow.qml、MainRootWindow.qml这些。用Qt Creator打开这些文件改完之后重新编译就能看到效果。这个过程能帮你熟悉QGC的工程结构和编译流程而且风险很低。提示改QML的时候Qt Creator有实时预览功能但QGC的QML依赖一些C注册的类型预览可能不完整。最靠谱的方式还是编译后运行看效果。5.2 添加自定义遥测数据面板如果你想让QGC显示一些官方没有的遥测数据比如自定义传感器的读数那就需要动C代码了。QGC的遥测数据流是从MAVLink消息解析出来的解析后的数据会存到Vehicle对象里。你可以找到src/Vehicle/Vehicle.h和Vehicle.cc在里面添加新的属性然后在QML里绑定显示。具体步骤是先在Vehicle类里加一个Q_PROPERTY然后在MAVLink消息处理的地方更新这个属性的值最后在QML里用vehicle.你的属性名来显示。这个过程涉及到Qt的属性系统和信号槽机制如果你不熟悉建议先补一下这方面的基础。MAVLink消息的定义在src/comm/MAVLinkProtocol和libs/mavlink里。如果你想解析自定义的MAVLink消息需要在MAVLink的消息定义文件里加上你的消息ID和字段然后重新生成MAVLink库。这一步稍微复杂一点但QGC的文档里有说明跟着做就行。5.3 修改航线规划逻辑的注意事项航线规划是QGC的核心功能之一相关代码主要在src/MissionManager目录下。如果你想改航线的生成逻辑比如自动添加航点、修改航点间距等需要仔细阅读MissionController和PlanManager这两个类。修改这部分代码的风险比较高因为航线规划涉及到与飞控的通信协议改错了可能导致飞控执行异常。我的建议是先在模拟环境下测试用PX4的SITL软件在环仿真配合QGC确认逻辑没问题之后再上真机。另外QGC的航线规划支持多种协议比如MAVLink的Mission协议和Survey协议。如果你要加新的规划模式需要同时改UI和后台逻辑工作量不小。建议先从简单的修改开始比如调整默认的航点高度、修改航线的默认速度等。6. 实操心得与避坑清单6.1 版本匹配是最大的坑我踩过的最大的坑就是版本不匹配。QGC的源码版本、Qt版本、编译器版本、MAVLink版本这几个东西必须互相兼容。我曾经用Qt 5.12去编译QGC 4.2结果报了一堆莫名其妙的错误折腾了一整天最后换成Qt 5.15.2十分钟就编过了。所以我的建议是在开始编译之前先去QGC的GitHub仓库看一下你那个分支的CI配置文件一般在.github/workflows或者.travis.yml里里面会写清楚用的什么版本的Qt、什么版本的编译器。照着那个配置来能省掉90%的版本问题。6.2 磁盘空间和内存要留足前面提过QGC编译很吃资源。我再强调一遍磁盘至少留80G内存至少16G。如果你用虚拟机编译记得把虚拟磁盘设成动态扩展并且给足初始空间。我曾经在一个50G的虚拟机上编译编到一半磁盘满了清理了半天才继续。内存不足的问题在链接阶段特别明显。如果你看到链接器被kill不要怀疑代码有问题就是内存不够。加swap或者降低并行数都能解决。6.3 不要轻易改核心通信代码QGC的核心通信代码在src/comm目录下包括MAVLink协议解析、串口通信、UDP/TCP通信等。这部分代码非常敏感改错一个字节就可能导致通信失败。如果你只是想加功能尽量在应用层做不要动底层通信。如果确实需要改通信协议比如加自定义的MAVLink消息建议先在MAVLink的XML定义文件里加然后用官方的生成工具重新生成代码而不是手动改生成的C文件。手动改的话下次重新生成就被覆盖了。6.4 善用日志和调试工具QGC内置了日志系统可以在运行时输出调试信息。你可以在代码里用qDebug()、qWarning()、qCritical()来打日志然后在Qt Creator的Application Output窗口里看。如果是在命令行运行日志会直接打到终端。另外QGC支持MAVLink Inspector功能可以实时查看飞控发过来的MAVLink消息。这个功能在调试通信问题时非常有用。你可以在QGC的设置里打开它或者直接在代码里加断点调试。6.5 常见问题速查表问题现象可能原因解决办法编译报错找不到头文件缺少开发库apt安装对应的-dev包Unknown module in QTQt模块未安装用Qt安装器补装模块链接时报undefined reference库未链接或链接顺序不对检查.pro文件里的LIBS配置链接器被kill内存不足加swap或降低并行编译数运行闪退无界面Qt插件路径不对设置QT_PLUGIN_PATH环境变量运行报OpenSSL符号错误OpenSSL版本不匹配使用QGC自带的OpenSSL或手动编译1.1版本QML界面不更新编译缓存未清理Clean All后重新Run qmake和Build飞控连接不上QGC串口权限或波特率不对检查用户是否在dialout组确认波特率设置6.6 关于代码对齐和编辑器的小技巧有人提到Qt Creator的代码对齐快捷键不好用这个我也有同感。Qt Creator默认的格式化快捷键是CtrlI但它只对选中的代码生效而且格式化规则比较保守。如果你想要更强大的格式化功能可以装一个ClangFormat插件在Beautifier设置里配置。QGC的源码里自带了一个.clang-format文件你可以直接用这个配置来格式化保持和官方代码风格一致。另外Qt Creator的代码补全有时候会卡特别是在大工程里。你可以在Options - C - Code Model里把“Indexing”相关的选项调一下比如关掉后台索引或者增加索引的线程数。不过这些调整因机器而异自己试一下找到最顺手的配置就行。7. 编译之后的下一步编译跑通只是第一步真正的二次开发才刚刚开始。我的建议是先花点时间把QGC的工程结构摸清楚知道哪个目录放什么代码哪个类负责什么功能。然后找一个你感兴趣的小功能试着改一改跑一跑看看效果。这个过程比看文档学得快得多。QGC的社区比较活跃遇到问题可以去GitHub的Issues里搜一搜大概率有人遇到过类似的问题。另外QGC的开发者文档虽然不算特别详细但关键部分都有说明值得一读。最后再分享一个小技巧如果你在编译过程中遇到了奇怪的错误先别急着改代码试试删掉整个build目录重新Run qmake和Build。很多时候问题只是编译缓存不一致导致的清理一下就好了。这个习惯帮我省了很多无谓的调试时间。