📚 课程目录第2章 QGC源码编译

2. QGC 源码编译：从拉取到跑起来

这一章，咱们来搞定 QGC 的编译环境。说实话，很多初学者都卡在这一步。不是代码写不出来，而是环境搭不起来。我见过太多人，GitHub 上点个 Star 很积极，一说到编译就头疼。

别担心。今天我就带你走一遍完整的流程。从拉取代码，到配置环境，再到解决那些烦人的编译错误。你跟着做，肯定能跑起来。

2.1 从 GitHub 拉取源码

首先，你得把 QGC 的源码弄到本地。这一步很简单，但有几个细节要注意。

核心命令：

git clone --recursive https://github.com/mavlink/qgroundcontrol.git

注意那个 --recursive 参数。QGC 依赖很多子模块，比如 mavlink 库、Qt 的第三方组件。不加这个参数，你拉下来的代码是不完整的。编译的时候会报一堆找不到头文件的错误。

我个人习惯用 SSH 协议拉取，省得每次输密码。如果你配置过 SSH Key，可以用这个：

git clone --recursive git@github.com:mavlink/qgroundcontrol.git

拉取完成后，检查一下目录结构。你应该能看到 src、libs、qgroundcontrol.pro 这些关键文件。如果 libs 文件夹是空的，说明子模块没拉下来。这时候执行：

git submodule update --init --recursive

注意： 网络不好的时候，子模块容易拉取失败。我曾经在客户现场，用他们的内网拉了一下午。后来发现是代理没配好。如果你在公司内网，记得设置 git 代理：

git config --global http.proxy http://你的代理地址:端口

2.2 Windows 编译配置

Windows 下编译 QGC，主要靠 Qt Creator。我建议你用 Qt 5.15.2 版本。为什么是这个版本？因为 QGC 官方对这个版本支持最好。我试过 Qt 6，坑比较多，暂时不建议。

2.2.1 安装 Qt

去 Qt 官网下载 Qt Online Installer。安装时勾选以下组件：

组件	说明
Qt 5.15.2 (MSVC 2019 64-bit)	主编译器套件
Qt WebEngine	QGC 的 UI 依赖这个
Qt WebSockets	通信模块
Qt Serial Port	串口通信
Qt Location	地图相关
Qt Charts	图表显示

安装路径不要有中文和空格。我见过有人装在 C:\Program Files (x86) 下面，结果编译时路径解析出错。

2.2.2 配置编译器

打开 Qt Creator，进入 工具 -> 选项 -> Kits。确保你的 Kit 里选择了 MSVC 2019 64-bit 编译器。别用 MinGW，QGC 对 MSVC 支持更好。

小技巧： 如果你电脑上装了多个 Visual Studio 版本，记得在 Qt Creator 里手动指定编译器路径。我一般用 VS 2019 Community 版，够用了。

2.2.3 编译步骤

用 Qt Creator 打开 qgroundcontrol.pro
选择 Release 模式（Debug 模式编译慢，而且文件巨大）
点击构建按钮
去泡杯咖啡，第一次编译大概需要 15-30 分钟

编译完成后，在 build-xxx-Release 目录下找到 QGroundControl.exe。双击能跑起来，就算成功了。

2.3 Linux 编译配置

Linux 下编译相对简单。我主要在 Ubuntu 20.04 和 22.04 上测试过。其他发行版大同小异。

2.3.1 安装依赖

sudo apt-get update
sudo apt-get install build-essential cmake git
sudo apt-get install qt5-default qttools5-dev-tools
sudo apt-get install libqt5serialport5-dev libqt5websockets5-dev
sudo apt-get install libqt5opengl5-dev libqt5svg5-dev
sudo apt-get install qtwebengine5-dev libqt5webchannel5-dev
sudo apt-get install libqt5location5-dev qtlocation5-dev
sudo apt-get install libqt5charts5-dev libqt5sql5-sqlite
sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev
sudo apt-get install libsdl2-dev libsdl2-2.0-0

嗯，这里要注意。不同 Ubuntu 版本，包名可能不一样。比如 Ubuntu 22.04 里 qt5-default 已经被移除了。你需要手动安装 qtbase5-dev。

2.3.2 编译命令

cd qgroundcontrol
mkdir build
cd build
cmake ..
make -j$(nproc)

-j$(nproc) 参数能利用所有 CPU 核心并行编译。我第一次编译时没加这个参数，等了快一个小时。加了之后，十几分钟就搞定了。

常见问题： 如果 cmake 报错找不到 Qt，说明你的 Qt 路径没配置对。试试这个：

export CMAKE_PREFIX_PATH=/usr/lib/x86_64-linux-gnu/cmake/Qt5

2.4 macOS 编译配置

macOS 下编译，我建议用 Homebrew 安装依赖。别用 MacPorts，那个坑太多。

2.4.1 安装 Homebrew 和依赖

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install qt@5
brew install cmake
brew install pkg-config

安装完成后，需要把 Qt 加入 PATH：

export PATH="/usr/local/opt/qt@5/bin:$PATH"

2.4.2 编译

cd qgroundcontrol
mkdir build && cd build
cmake ..
make -j$(sysctl -n hw.ncpu)

macOS 上编译，最容易出问题的是 WebEngine 组件。如果你遇到 WebEngine 相关的错误，检查一下 Qt 安装是否完整。我建议用 brew reinstall qt@5 重装一次。

2.5 常见编译错误解决

这部分是我最想跟你分享的。编译错误千奇百怪，但归根结底就那么几类。我整理了一个表格，你遇到问题可以直接查。

错误信息	原因	解决方案
`Cannot find -lQt5WebEngineWidgets`	WebEngine 组件未安装	重新安装 Qt，勾选 WebEngine
`GL/gl.h: No such file or directory`	缺少 OpenGL 头文件	Linux: `sudo apt install mesa-common-dev`
`undefined reference to 'vtable for ...'`	Q_OBJECT 宏未正确解析	清理 build 目录，重新 qmake 或 cmake
`fatal error: 'mavlink/common/mavlink.h' file not found`	子模块未拉取	`git submodule update --init --recursive`
`error: 'QWebEnginePage' has not been declared`	Qt 版本不匹配	确保使用 Qt 5.15.x，不是 Qt 6
`collect2: error: ld returned 1 exit status`	链接错误，通常是库缺失	检查依赖库是否完整安装

避坑指南： 我曾经在 Windows 上遇到一个诡异的错误——编译到 90% 突然报错，说某个 .obj 文件损坏。折腾了半天，最后发现是杀毒软件在后台扫描编译目录，把临时文件锁住了。关掉杀毒软件，重新编译，一次通过。

2.6 知识体系总览

为了让你对整个编译流程有个全局认识，我画了一张图。你可以把它当作路线图，遇到问题时对照着看。

2.7 写在最后

编译环境搭好了，你的 QGC 二次开发之路就迈出了最关键的一步。别怕出错，每个错误都是学习的机会。我刚开始搞 QGC 的时候，光编译就折腾了三天。现在回头看，那些坑反而让我对 QGC 的依赖关系理解得更深。

如果你在编译过程中遇到问题，先对照上面的表格自查。实在解决不了，可以去 QGC 的 GitHub Issues 里搜一下。大概率有人遇到过同样的问题。