第2章 QGC安装与编译：Windows/Linux/Mac环境搭建、源码编译、常见编译错误解决

说实话，QGC（QGroundControl）的安装编译，是很多初学者第一道坎。我记得第一次接触这个项目时，光环境配置就折腾了两天。但别怕，这东西说白了就是一套标准流程——你只要按步骤来，基本不会出大问题。

这一章，我会把Windows、Linux、Mac三个平台的搭建方法都过一遍。重点放在Windows和Ubuntu上，因为这是绝大多数开发者的选择。Mac用户也别急，流程大同小异。

2.1 环境准备：你需要什么？

先列个清单，看看你电脑上缺什么。我个人习惯在开始前先检查一遍，免得编译到一半才发现少东西。

组件	版本要求	说明
Qt框架	5.15.x（推荐5.15.2）	QGC核心UI框架，必须安装Desktop组件
CMake	≥3.16	构建系统，用于生成Makefile或项目文件
编译器	GCC 9+ / MSVC 2019+ / Clang 12+	根据平台选择，C++17支持是硬性要求
Git	≥2.20	拉取源码和子模块
Ninja（可选）	≥1.10	加速编译，比Make快不少

2.2 Windows环境搭建

Windows用户最多，问题也最多。我先把流程走一遍，然后重点说几个坑。

2.2.1 安装Qt

1. 去Qt官网下载Qt Online Installer（或者用国内镜像，快很多）
2. 安装时选择Qt 5.15.2 → MSVC 2019 64-bit → Qt Charts → Qt WebEngine
3. 注意：一定要勾选Qt WebEngine，否则编译会报找不到QtWebEngineWidgets的错误
4. 安装路径不要有中文和空格，我见过有人因为路径里有"Program Files (x86)"导致编译失败

2.2.2 安装编译工具

• Visual Studio 2019/2022：安装时勾选"使用C++的桌面开发"
• CMake：从官网下载安装包，安装时勾选"Add CMake to system PATH"
• Git for Windows：默认选项即可

2.2.3 拉取源码

git clone --recursive https://github.com/mavlink/qgroundcontrol.git
cd qgroundcontrol
git submodule update --init --recursive

这里有个细节：--recursive参数会同时拉取所有子模块。如果网络不好，子模块可能下载失败。我遇到过好几次，解决方案是手动进入libs/目录，逐个执行git submodule update --init。

2.2.4 编译

mkdir build
cd build
cmake .. -G "Visual Studio 16 2019" -A x64
cmake --build . --config Release

嗯，这里要注意：-G参数指定生成器，Visual Studio版本号要对上。VS 2019是"16"，VS 2022是"17"。我第一次用VS 2022时忘了改版本号，结果CMake报了一堆错。

2.3 Linux环境搭建（以Ubuntu 20.04/22.04为例）

Linux下编译比Windows顺畅很多。我自己的主力开发机就是Ubuntu 22.04，基本没遇到什么大坑。

2.3.1 安装依赖

sudo apt update
sudo apt install build-essential cmake git ninja-build
sudo apt install qt5-default qttools5-dev qtwebengine5-dev libqt5charts5-dev
sudo apt install libgl1-mesa-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev

注意：Ubuntu 22.04的仓库里没有qt5-default这个包了。如果你用22.04，需要手动安装Qt 5.15.3：

sudo apt install qtbase5-dev qttools5-dev qtwebengine5-dev libqt5charts5-dev

2.3.2 编译

git clone --recursive https://github.com/mavlink/qgroundcontrol.git
cd qgroundcontrol
mkdir build && cd build
cmake .. -G Ninja
ninja

用Ninja比Make快不少，尤其是第一次全量编译时。我实测过，Ninja比Make快了大概30%。

2.4 macOS环境搭建

Mac用户相对少，但流程其实最简单。因为Homebrew把依赖都包好了。

# 安装Homebrew（如果没有的话）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖
brew install cmake ninja qt@5
brew link qt@5 --force

# 拉取源码
git clone --recursive https://github.com/mavlink/qgroundcontrol.git
cd qgroundcontrol

# 编译
mkdir build && cd build
cmake .. -G Ninja -DCMAKE_PREFIX_PATH=$(brew --prefix qt@5)
ninja

这里有个坑：macOS的Qt安装路径和Linux不一样，必须手动指定CMAKE_PREFIX_PATH。我第一次编译时忘了加这个参数，结果CMake找不到Qt库，报了一堆"Could not find Qt5"的错误。

2.5 常见编译错误及解决方案

这部分是我最想说的。我在项目里遇到过各种奇奇怪怪的编译错误，下面列几个高频的，你遇到了直接照搬解决方案就行。

错误信息	原因	解决方案
Could not find Qt5WebEngineWidgets	未安装Qt WebEngine组件	重新运行Qt安装器，勾选WebEngine组件
fatal error: 'gst/gst.h' file not found	缺少GStreamer开发库	Linux: sudo apt install libgstreamer1.0-dev macOS: brew install gstreamer
undefined reference to 'vtable for ...'	Q_OBJECT宏未正确处理	清理build目录，重新运行cmake和编译
error: 'QStringView' is not a member of 'Qt'	Qt版本过低（低于5.15）	升级Qt到5.15.x版本
ninja: error: loading 'build.ninja': No such file	CMake配置未完成	检查CMake输出，确认没有错误后重新运行cmake

2.6 本章知识体系

下面这张图把整个安装编译流程串起来了。你跟着这个流程走，基本不会迷路。

2.7 验证安装是否成功

编译完成后，在build/目录下会生成可执行文件。Windows下是Release/qgroundcontrol.exe，Linux/Mac下是staging/qgroundcontrol。

运行前建议先做两件事：

1. 检查版本号：./qgroundcontrol --version，确认是你编译的版本
2. 检查依赖库：ldd qgroundcontrol（Linux）或otool -L qgroundcontrol（Mac），确保没有缺失的.so或.dylib

如果一切正常，启动后你会看到QGC的主界面。第一次启动会弹出设置向导，直接关掉就行——那是给最终用户用的，我们开发者直接进主界面调试。