Windows平台Qt 5.15.2与MSVC编译QGC 4.4全流程避坑手册

第一次尝试在Windows上编译QGroundControl（QGC）时，我花了整整两天时间解决各种报错问题。从Qt版本冲突到子模块更新失败，再到MSVC编译器特有的警告处理，每一步都可能成为新手开发者的"拦路虎"。本文将分享一套经过实战验证的完整流程，帮助无人机开发者和学生绕过这些陷阱，一次性完成QGC 4.4稳定版的编译。

1. 环境准备与源码获取

1.1 工具链精准匹配

QGC 4.4稳定版对工具链有严格要求，任何版本偏差都可能导致编译失败。以下是经过验证的组合：

安装Qt时特别注意勾选：

• MSVC 2019 64-bit组件
• Qt Charts模块（QGC依赖项）
• Qt Quick Compiler（可选但推荐）

1.2 源码克隆的进阶技巧

官方文档中简单的git clone命令在实际操作中常因网络问题失败。这里推荐两种可靠方案：

方案A：分步克隆（推荐）

bash复制# 先克隆主仓库（不包含子模块）
git clone -b Stable_V4.4 https://github.com/mavlink/qgroundcontrol.git
cd qgroundcontrol

# 使用国内镜像加速子模块更新
git config --global url."https://hub.fastgit.org".insteadOf https://github.com
git submodule update --init --recursive

方案B：存档下载（网络不稳定时备用）

1. 从GitHub下载Stable_V4.4的源码zip包
2. 单独下载libs/mavlink子模块的zip
3. 手动解压到正确目录结构

提示：若子模块更新卡顿，可尝试修改.gitmodules文件中的URL为国内镜像地址（如https://gitee.com/mirrors/mavlink.git）

2. Qt Creator项目配置精要

2.1 编译器与构建套件选择

打开qgroundcontrol.pro前，需确保Qt Creator正确识别了工具链：

1. 进入工具 → 选项 → Kits
2. 验证MSVC2019 64-bit套件包含：
   • 正确的Qt版本（5.15.2）
   • 匹配的CMake工具（≥3.15）
   • 对应的调试器（CDB）

常见配置错误排查：

• 若出现"找不到编译器"错误，检查VS2019的"使用C++的桌面开发"是否安装完整
• 遇到qmake路径问题，手动指定%QT_DIR%\5.15.2\msvc2019_64\bin\qmake.exe

2.2 项目参数调优

在Projects → Build Settings中调整以下关键参数：

plaintext复制构建目录：建议设为../build-QGC（避免源码污染）
构建步骤：添加自定义qmake参数 CONFIG+=installer
环境变量：追加 PATH=%QT_DIR%\Tools\QtCreator\bin

对于8GB以下内存的设备，建议修改.pro文件：

qmake复制# 添加内存优化选项
QMAKE_CXXFLAGS += /Zm500
QMAKE_LFLAGS += /LARGEADDRESSAWARE

3. 编译过程中的典型问题解决方案

3.1 警告处理的艺术

MSVC特有的/WX（视警告为错误）和/W3（警告等级）常导致编译中断。不同于简单删除这些标志，更专业的做法是：

1. 定位QGCCommon.pri中的警告设置
2. 修改为渐进式警告策略：

qmake复制# 原始设置
# QMAKE_CXXFLAGS_WARN_ON += /WX /W3

# 优化设置（允许特定警告）
QMAKE_CXXFLAGS_WARN_ON += /W3 /wd4068 /wd4996

其中/wd开头的参数用于禁用特定警告编号，常见可忽略的警告包括：

• 4068：未知pragma指令
• 4996：函数被声明为已弃用

3.2 依赖项缺失的修复

当出现"missing vcruntime140.dll"等错误时，需要部署VC运行库：

bash复制# 使用Qt自带的部署工具
windeployqt --compiler-runtime qgroundcontrol.exe

对于更复杂的依赖问题，可手动检查：

1. 在Dependencies工具中分析exe文件
2. 将缺失的dll从%VCINSTALLDIR%redist\MSVC\14.xx复制到输出目录

4. 二次开发实用技巧

4.1 UI定制实战

修改主界面标题的正确姿势不是直接硬编码，而是通过资源系统实现：

1. 在qgcresources.qrc中添加字符串资源

xml复制<qresource>
    <string name="app_title">我的无人机控制站</string>
</qresource>

2. 在MainRootWindow.qml中引用：

qml复制title: qsTrId("app_title")

4.2 多语言支持进阶

官方推荐的汉化方法存在更新丢失风险。更健壮的做法：

1. 创建自定义翻译文件translations/qgc_zh.ts
2. 修改.pro文件自动包含：

qmake复制TRANSLATIONS += $$PWD/translations/qgc_zh.ts

3. 使用脚本自动化更新：

bash复制lupdate qgroundcontrol.pro -no-obsolete
linguist translations/qgc_zh.ts
lrelease translations/qgc_zh.ts

4.3 插件开发环境搭建

要为QGC开发自定义插件，需要配置独立开发环境：

1. 创建插件模板：

bash复制python3 tools/create_plugin.py MyPlugin --output=../QGCPlugin

2. 在customPlugins.pri中添加：

qmake复制include($$PWD/../QGCPlugin/MyPlugin/MyPlugin.pri)

3. 使用影子构建确保热重载：

bash复制mkdir build-shadow
cd build-shadow
qmake ../qgroundcontrol.pro "QGC_SHADOW_BUILD=ON"