保姆级教程：在Ubuntu 20.04上用Qt 5.12.8从源码编译QGC地面站（附常见编译错误解决）
保姆级教程：在Ubuntu 20.04上用Qt 5.12.8从源码编译QGC地面站（附常见编译错误解决）
第一次尝试在Ubuntu上编译QGroundControl时，我花了整整两天时间解决各种依赖和版本冲突问题。从Qt版本不匹配到子模块初始化失败，再到莫名其妙的wayland组件缺失——这些坑几乎让每个新手开发者抓狂。本文将用最详细的步骤带你避开所有雷区，从零开始构建可二次开发的QGC环境。
1. 系统环境准备与依赖安装
Ubuntu 20.04作为长期支持版本，其稳定性使其成为QGC开发的理想选择。但默认安装的组件往往不能满足编译需求，我们需要先打好基础环境。
必须安装的基础依赖包：
sudo apt update sudo apt install -y build-essential cmake git ninja-build \ libssl-dev libsdl2-dev libgstreamer-plugins-base1.0-dev \ libgstreamer1.0-dev g++-9 libopencv-dev libqt5opengl5-dev注意：Ubuntu 20.04默认gcc版本为9.3.0，而Qt 5.12.8需要至少gcc 7.5。如果系统有其他版本gcc，建议通过update-alternatives切换：
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 90 sudo update-alternatives --config gcc
关键组件版本要求：
| 组件 | 最低版本 | 推荐版本 | 验证命令 |
|---|---|---|---|
| CMake | 3.16 | 3.22+ | cmake --version |
| GCC | 7.5 | 9.3 | gcc --version |
| Python | 3.6 | 3.8 | python3 --version |
我曾遇到因OpenSSL版本不兼容导致Qt网络模块编译失败的情况，解决方案是安装特定开发包：
sudo apt install -y libssl1.1 libssl-dev2. Qt 5.12.8定制化安装
官方提供的在线安装器往往包含不必要的组件，而QGC开发只需要核心模块。推荐使用以下精简安装方案：
下载离线安装包：
wget https://download.qt.io/archive/qt/5.12/5.12.8/qt-opensource-linux-x64-5.12.8.run chmod +x qt-opensource-linux-x64-5.12.8.run选择安装组件（关键步骤）：
- Qt 5.12.8 → Desktop gcc 64-bit
- Qt Charts
- Qt Quick Controls 2
- Qt WebEngine
- Qt Script (Deprecated)
警告：千万不要勾选"Source Components"，这会导致后续编译冲突。我曾因此浪费3小时排查qmake错误。
配置环境变量：
echo 'export QT_DIR=/opt/Qt5.12.8/5.12.8/gcc_64' >> ~/.bashrc echo 'export PATH=$QT_DIR/bin:$PATH' >> ~/.bashrc source ~/.bashrc验证安装是否成功：
qmake --version # 应输出：QMake version 3.13. QGC源码获取与子模块处理
官方仓库的Stable_V4.1分支是最稳定的二次开发起点，但子模块管理是个技术活。
克隆指定分支：
git clone --recursive https://github.com/mavlink/qgroundcontrol.git -b Stable_V4.1 cd qgroundcontrol补救子模块初始化（常见问题解决方案）： 当网络不稳定导致子模块下载失败时，执行：
git submodule sync --recursive git submodule update --init --recursive --depth 1我曾遇到libs/qmlglsink子模块无法下载的情况，这是国内开发者常见问题。替代方案：
rm -rf libs/qmlglsink git clone https://gitee.com/mirrors_groestlcoin/qmlglsink.git libs/qmlglsink关键子模块清单：
- mavlink (v2.0)
- QtLocation (5.12.8)
- QtPositioning (5.12.8)
- qmlglsink (特定gstreamer插件)
4. 编译配置与排错指南
进入最关键的编译阶段，这里每一步都可能隐藏着陷阱。
生成构建配置：
mkdir build && cd build cmake .. -GNinja \ -DCMAKE_BUILD_TYPE=Release \ -DQT_QMAKE_EXECUTABLE=$QT_DIR/bin/qmake \ -DCMAKE_PREFIX_PATH=$QT_DIR高频错误解决方案：
- qtwayland缺失：
cd /tmp git clone https://github.com/qt/qtwayland.git cd qtwayland git checkout v5.12.8 $QT_DIR/bin/qmake make -j$(nproc) sudo make install- GL/gl.h找不到：
sudo apt install -y mesa-common-dev libglu1-mesa-dev- undefined reference to
qInitResources_*： 这是qrc资源编译问题，清理后重建：
rm -rf * && cmake .. -GNinja && ninja完整编译命令：
ninja -j$(nproc)编译成功后，在build/staging目录会生成可执行文件。建议创建快捷方式：
ln -s $(pwd)/staging/QGroundControl ~/Desktop/QGC5. 开发环境优化与调试技巧
Qt Creator配置要点：
- 在"Kits"中添加自定义Qt版本，指向
/opt/Qt5.12.8/5.12.8/gcc_64 - 设置CMake路径为
/usr/bin/cmake - 在"Build & Run"中添加自定义构建步骤：
Command: ninja Arguments: -j8 Working directory: %{buildDir}
调试线程技巧： 当QGC出现卡顿时，快速定位线程问题：
ps -T -p $(pgrep QGroundControl)内存泄漏检测： 在Qt Creator的Analyzer菜单中使用Valgrind工具，特别注意：
- QML对象未释放
- MAVLink消息队列堆积
- 视频解码器资源泄漏
6. 二次开发快速入门
项目结构关键目录：
├── src/ │ ├── Vehicle/ # 载具控制核心 │ ├── QmlControls/ # 自定义QML组件 │ └── Audio/ # 语音通知系统 ├── libs/ │ ├── mavlink/ # 通信协议 │ └── qmlglsink/ # 视频渲染 └── resources/ # 界面资源文件修改UI的推荐流程：
- 复制
resources/qml/下的原始QML文件 - 在
src/QmlControls/创建自定义组件 - 通过
qrc资源系统覆盖默认UI
通信协议扩展示例： 在src/comm/MAVLinkProtocol.cc中添加自定义消息处理：
void MAVLinkProtocol::_handleCustomMessage(mavlink_message_t message) { if (message.msgid == MAVLINK_MSG_ID_CUSTOM_COMMAND) { emit customCommandReceived(message); } }记得在mavlink/include/mavlink/v2.0/common/mavlink_msg_custom_command.h中定义消息结构体。
7. 持续集成与自动化构建
对于团队开发，建议配置GitLab CI自动化流程：
.gitlab-ci.yml示例：
stages: - build qgc_build: stage: build image: ubuntu:20.04 script: - apt update && apt install -y ... - wget https://qt.mirror.constant.com/archive/qt/5.12/5.12.8/qt-opensource-linux-x64-5.12.8.run - chmod +x qt-opensource-linux-x64-5.12.8.run - ./qt-opensource-linux-x64-5.12.8.run --script qt_installer_script.qs - git clone --recursive https://github.com/mavlink/qgroundcontrol.git - cd qgroundcontrol && mkdir build && cd build - cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release - ninja artifacts: paths: - qgroundcontrol/build/staging/私有化部署技巧：
- 使用
ccache加速重复编译：sudo apt install ccache echo 'export PATH="/usr/lib/ccache:$PATH"' >> ~/.bashrc - 搭建本地Qt镜像源：
rsync -avz --delete qt.mirror.constant.com::qtarchive /mnt/qt_mirror
8. 性能调优实战案例
启动速度优化： 在src/QGCApplication.cc中禁用非必要插件：
QCoreApplication::setAttribute(Qt::AA_DisableShaderDiskCache); QQuickWindow::setSceneGraphBackend(QSGRendererInterface::OpenGL);内存占用分析： 使用Massif可视化工具：
valgrind --tool=massif --massif-out-file=massif.out ./QGroundControl ms_print massif.out > analysis.txtUI渲染性能提升：
- 在QML中使用
Loader延迟加载复杂组件 - 对频繁更新的数据使用
Qt.binding代替直接赋值 - 启用QML缓存：
import QtQuick 2.12 Item { Component.onCompleted: Qt.createQmlObject('import QtQuick 2.12; Rectangle{}', parent, "cache") }
9. 跨平台构建技巧
Windows交叉编译准备： 在Ubuntu上安装MinGW工具链：
sudo apt install -y g++-mingw-w64-x86-64生成Windows构建配置：
mkdir build-win && cd build-win cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchain/Toolchain-mingw64.cmake \ -DQT_QMAKE_EXECUTABLE=$QT_DIR/bin/qmakemacOS构建注意事项：
- 需要额外安装：
brew install openssl@1.1 libuv - 解决证书问题：
export OPENSSL_ROOT_DIR=/usr/local/opt/openssl@1.1
10. 插件开发进阶指南
创建自定义插件模板：
./tools/create_new_plugin.sh MyCustomPlugin插件注册机制： 在src/Plugins/Plugin.cc中扩展：
void Plugin::registerCustomPlugin() { qmlRegisterType<MyCustomPlugin>("QGroundControl.MyPlugin", 1, 0, "MyPlugin"); }插件通信架构：
graph LR A[MainApp] -->|Signal| B(Plugin) B -->|Slot| C[Vehicle] C -->|MAVLink| D[Hardware]调试插件加载顺序： 设置环境变量查看加载流程：
export QGC_DEBUG_PLUGINS=1 ./QGroundControl