保姆级教程：在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-dev

2. 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.1

3. 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 toqInitResources_*：这是qrc资源编译问题，清理后重建：

rm -rf * && cmake .. -GNinja && ninja

完整编译命令：

ninja -j$(nproc)

编译成功后，在build/staging目录会生成可执行文件。建议创建快捷方式：

ln -s $(pwd)/staging/QGroundControl ~/Desktop/QGC

5. 开发环境优化与调试技巧

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.txt

UI渲染性能提升：

在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/qmake

macOS构建注意事项：

需要额外安装：
```
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

保姆级教程：在Ubuntu 20.04上用Qt 5.12.8从源码编译QGC地面站（附常见编译错误解决）