Qt 5.15.2 Android Studio 环境搭建 QGC 4.4 开发环境全流程附常见报错解决方案如果你是一位无人机开发者或者对地面站软件GCS的二次开发感兴趣那么 QGroundControlQGC这个名字对你来说一定不陌生。作为一款功能强大、开源且支持 MAVLink 协议的无人机地面控制站QGC 允许开发者进行深度定制和功能扩展以满足特定行业或研究需求。然而将 QGC 成功编译并部署到 Android 平台却常常成为开发者面临的第一道技术门槛。这个过程远不止是“安装几个软件”那么简单。它涉及到 Qt 框架、Android NDK、Java SDK 以及一系列构建工具链的精确匹配与配置。一个版本号的差异一个环境变量的错配都可能导致数小时的编译失败。网络上虽然不乏教程但大多零散或是基于旧版本或是忽略了 Windows 平台下那些“坑点”。对于初次接触 QGC 安卓开发的工程师来说从零开始搭建一个稳定、可复现的构建环境本身就是一项极具挑战性的任务。本文旨在为你提供一份详尽、经过实战检验的 Windows 平台 QGC 4.4 安卓开发环境搭建指南。我们将从最基础的软件安装开始一步步深入到 Qt Creator 的配置、源码的获取与编译并重点剖析那些令人头疼的典型报错及其背后的原理与解决方案。无论你是希望将 QGC 移植到定制化安卓设备还是想研究其内部架构这篇文章都将为你扫清环境搭建的障碍让你能将精力集中在真正的开发工作上。1. 基石核心工具链的精确部署搭建 QGC 安卓开发环境本质上是在构建一个跨平台的编译流水线。这条流水线需要将 C/Qt 代码通过特定的工具链最终转化为能在 ARM 架构 Android 设备上运行的 APK 文件。因此第一步就是确保流水线上的每一个“齿轮”——即各个核心工具——的型号和安装位置都完全匹配。1.1 Java 开发工具包 (JDK) 的选择与配置QGC 4.4 的安卓构建系统依赖于 Gradle而 Gradle 的运行需要 Java 环境。官方文档明确指出需要JDK 11。这是一个硬性要求使用 JDK 8 或更高版本的 JDK 17 都可能导致不可预见的兼容性问题。安装步骤下载访问 Oracle 官网或 OpenJDK 发行站如 Adoptium下载 JDK 11 的 Windows x64 安装程序或压缩包。安装/解压如果使用安装程序建议安装路径不要包含中文或空格例如C:\Dev\Java\jdk-11.0.xx。如果使用 ZIP 包直接解压到目标目录即可。配置环境变量这是关键一步需要设置JAVA_HOME并将bin目录加入PATH。右键点击“此电脑” - “属性” - “高级系统设置” - “环境变量”。在“系统变量”中点击“新建”变量名输入JAVA_HOME变量值输入你的 JDK 安装路径例如C:\Dev\Java\jdk-11.0.xx。在“系统变量”中找到Path变量双击编辑点击“新建”添加%JAVA_HOME%\bin。验证安装打开命令提示符CMD或 PowerShell输入以下命令java -version javac -version如果正确显示 Java 版本为 11则说明配置成功。这一步的准确性直接影响后续 Android SDK 工具如sdkmanager能否正常运行。1.2 Android 开发环境的基石SDK 与 NDKAndroid SDK 提供了构建安卓应用所需的基础库和工具而 NDKNative Development Kit则是编译 C/C 代码为安卓原生库的关键。对于 QGC 这种 Qt/C 项目NDK 的版本至关重要。核心要点SDK 工具选择避免使用过时或图形化的 SDK Manager。推荐使用 Google 提供的命令行工具cmdline-tools进行管理它更轻量、可脚本化且与 CI/CD 流程兼容。NDK 版本锁定根据 QGC 4.4 的构建要求我们需要NDK 21.3.6528147。使用其他版本如 NDK 25几乎必然导致编译错误。推荐安装流程创建一个干净的目录作为 Android SDK 的根目录例如D:\Android\Sdk。下载commandlinetools。你需要找到适用于 Windows 且版本较旧的包。一个已知可用的版本是commandlinetools-win-9123335_latest.zip对应版本 8.0。你可以通过修改 Qt Creator 内部的配置文件或直接搜索此版本进行下载。将下载的 ZIP 包解压到 SDK 根目录下的cmdline-tools\latest子目录中。最终路径应类似于D:\Android\Sdk\cmdline-tools\latest\bin\sdkmanager.bat。使用sdkmanager安装必需的包。以管理员身份打开命令提示符导航到latest\bin目录执行以下命令sdkmanager --sdk_rootD:\Android\Sdk platform-tools platforms;android-31 build-tools;31.0.0 ndk;21.3.6528147 emulator注意--sdk_root参数用于指定 SDK 根目录确保所有组件都安装到正确位置。命令执行过程中需要接受许可协议输入y或直接按回车。此方法能精准控制组件版本避免自动安装工具带来的版本冲突。1.3 Qt 5.15.2 LTS 的定制化安装Qt 5.15.2 是一个长期支持版本也是 QGC 4.4 官方指定的唯一版本。绝对不要尝试使用 Qt 5.12、5.14 或 Qt 6.x 系列它们会导致链接错误或运行时崩溃。安装注意事项使用在线安装器从 Qt 官网下载qt-unified-windows-x64-online.exe在线安装程序。配置镜像加速为了获得可接受的下载速度在启动安装程序时通过命令行指定国内镜像。在安装程序所在目录打开命令行执行qt-unified-windows-x64-online.exe --mirror https://mirrors.aliyun.com/qt/组件选择在组件选择页面务必勾选右上角的Archive复选框然后筛选出Qt 5.15.2。针对安卓开发必须选择的组件包括Qt 5.15.2-Android(选择 ARMv7 和/或 ARM64 架构)Qt 5.15.2-Qt ChartsQt 5.15.2-Qt Location(技术预览版)Qt 5.15.2-Qt Quick Controls 2同时在Developer and Designer Tools下确保安装了Qt Creator和对应的MinGW或MSVC编译器用于桌面调试。安装完成后启动 Qt Creator我们将在下一节进行关键的系统集成配置。2. 集成与配置打通 Qt 与 Android 的桥梁安装好各个独立组件只是第一步让它们在 Qt Creator 这个 IDE 中协同工作才是真正的挑战。Qt Creator 的“套件”Kit概念将编译器、调试器、Qt 版本和部署设备绑定在一起我们需要为安卓构建创建一个可用的套件。2.1 在 Qt Creator 中配置 Android 环境打开 Qt Creator进入工具-选项macOS 下为Qt Creator-偏好设置。定位配置页面在左侧面板中找到“设备”或“Kits”选项。不同版本的 Qt Creator 界面略有差异但核心配置项相同。我们需要配置的是“Android”相关设置。配置 JDK 路径在设备-Android选项卡下或Kits-Android找到JDK 位置。点击浏览指向你之前安装的 JDK 11 的根目录例如C:\Dev\Java\jdk-11.0.xx。Qt Creator 会自动检测其有效性。配置 Android SDK 与 NDK 路径在同一个界面找到Android SDK 位置指向你的 SDK 根目录例如D:\Android\Sdk。找到Android NDK 位置它通常位于 SDK 目录下的ndk文件夹内例如D:\Android\Sdk\ndk\21.3.6528147。请手动选择不要依赖自动检测。配置完成后界面通常会显示一个绿色的对勾或“已配置”状态并列出检测到的 SDK 平台、构建工具和 NDK 版本。请仔细核对 NDK 版本是否为21.3.6528147。下表总结了关键路径的配置示例配置项变量名 (可选)示例路径说明JDK 位置JAVA_HOMEC:\Dev\Java\jdk-11.0.xx必须为 JDK 11Android SDK 位置ANDROID_SDK_ROOTD:\Android\Sdk包含platforms,build-tools等Android NDK 位置ANDROID_NDK_ROOTD:\Android\Sdk\ndk\21.3.6528147必须为 21.3.6528147Android SDK 构建工具-D:\Android\Sdk\build-tools\31.0.0由sdkmanager安装可选配置 OpenSSL某些情况下QGC 的安卓构建可能需要 OpenSSL 库。你可以在Android 设置部分找到OpenSSL 二进制文件位置。你可以从可靠来源下载预编译的安卓版 OpenSSL并在此指定其路径。如果编译过程中未提示相关错误此步骤可暂缓。2.2 获取与准备 QGC 4.4 源代码QGC 使用 Git 进行版本管理并且包含了必须的子模块submodules。错误的克隆方式会导致代码不完整编译失败。正确的克隆与切换分支命令打开 Git Bash 或任何你熟悉的终端执行以下命令# 1. 克隆主仓库及其所有子模块使用 -j8 参数加速 git clone --recursive -j8 https://github.com/mavlink/qgroundcontrol.git # 2. 进入源码目录 cd qgroundcontrol # 3. 切换到 Stable_V4.4 分支这是与 Qt 5.15.2 对应的稳定分支 git checkout Stable_V4.4 # 4. 确保子模块也同步到该分支对应的提交 git submodule update --recursive重要提示切勿直接从 GitHub 下载 ZIP 压缩包因为 ZIP 包不包含.git信息无法获取子模块代码。完成以上步骤后你的本地仓库就准备好了。接下来在 Qt Creator 中点击文件-打开文件或项目导航到qgroundcontrol源码目录选择qgroundcontrol.pro文件打开。首次打开时Qt Creator 会提示你配置项目。在Configure Project页面你需要为安卓构建选择正确的套件。2.3 配置项目构建套件在 Qt Creator 左侧的“项目”模式或点击“配置项目”后进入的界面中你会看到“构建套件”的选择。取消桌面套件默认可能选中了Desktop Qt 5.15.2 MSVC2019 64bit之类的套件。为了编译安卓 APK请取消勾选所有桌面套件。选择安卓套件勾选名为Android Qt 5.15.2 Clang Multi-Abi或类似的套件。套件名称中应包含“Android”和“Clang”。检查构建配置确保在“构建设置”中活动构建配置通常是Release用于生成发布包或Debug用于调试。对于初次构建建议先使用Debug以便查看更详细的日志。配置构建设置在构建步骤-qmake的附加参数中通常不需要额外添加。但如果你需要禁用某些可选功能如 Airmap可以添加DEFINESDISABLE_AIRMAP。在运行设置中确保“部署配置”下已添加了安卓部署步骤并且目标设备已连接或已配置好安卓虚拟设备AVD。完成这些配置后理论上就可以点击左下角的“构建”按钮锤子图标进行编译了。然而现实往往比理想骨感我们接下来将直面那些最常见的“拦路虎”。3. 编译征途典型报错深度剖析与解决即使环境配置看似完美第一次构建 QGC 安卓版本也极少能一帆风顺。下面我将结合自己的踩坑经历详细分析几个高频出现的编译错误并提供经过验证的解决方案。3.1 错误一NDK 工具链路径错误与“找不到 clang”错误现象在构建过程中控制台输出类似如下的错误信息make: *** No rule to make target E:progromAndroidAndroidSDKndk21.3.6528147/toolchains/llvm/prebuilt/windows-x86_64/bin/clang, needed by ....o. Stop.或者错误信息中显示的路径异常如E:progromAndroid...缺少反斜杠。问题根源这个问题的核心在于Windows 路径分隔符反斜杠\在 Makefile 中被错误解析。Qt 的构建系统qmake生成的 Makefile 中包含了 NDK 的绝对路径。在 Unix 环境下路径使用正斜杠/作为分隔符而 Windows 使用反斜杠\。当 Makefile 在 Windows 下被 NDK 中的make工具处理时反斜杠可能被解释为续行符导致路径被截断或合并从而找不到clang编译器。解决方案我们不能直接修改生成的 Makefile因为它会在每次构建时被重新生成。正确的做法是修改传递给构建系统的环境变量确保其使用正斜杠。在 Qt Creator 中进入项目-构建环境。点击“详情”展开环境变量列表。找到ANDROID_NDK_ROOT这个变量。如果不存在点击“添加”新建一个。将其值设置为你的 NDK 路径但必须使用正斜杠。例如变量名: ANDROID_NDK_ROOT 变量值: D:/Android/Sdk/ndk/21.3.6528147注意将所有的\替换为/。同样地检查并确保ANDROID_SDK_ROOT也使用正斜杠。点击“应用”并重新构建项目。这个修改会确保在生成 Makefile 时NDK 的路径以正确的格式被写入从而解决编译器找不到的问题。3.2 错误二Git 工具命令缺失which, sed错误现象构建早期阶段提示‘which’ 不是内部或外部命令也不是可运行的程序或‘sed’ 不是内部或外部命令。问题根源QGC 的构建脚本在某些预处理步骤中使用了 Unix 风格的命令which用于查找命令路径和sed流编辑器。在 Windows 上这些命令通常由 Git for Windows 附带位于其安装目录的usr\bin子目录下。如果系统 PATH 环境变量或 Qt Creator 的构建环境 PATH 中没有包含这个目录就会导致命令找不到。解决方案有两种方法可以将 Git 的usr\bin目录添加到路径中方法 A修改系统环境变量永久生效找到 Git 的安装目录例如C:\Program Files\Git。将其下的usr\bin目录完整路径如C:\Program Files\Git\usr\bin添加到系统的PATH环境变量中。重启 Qt Creator以使更改生效。方法 B在 Qt Creator 项目设置中临时添加推荐这种方法只影响当前项目更为干净。在 Qt Creator 中进入项目-构建环境。点击“详情”展开环境变量列表。找到PATH变量点击“编辑”。在值列表的末尾添加 Git 的usr\bin目录路径使用分号分隔。点击“确定”并重新构建。3.3 错误三第三方库缺失如 nlohmann_json错误现象编译过程中提示找不到头文件例如fatal error: nlohmann/json.hpp: No such file or directory。问题根源QGC 依赖一些第三方库作为子模块如libevents而它又依赖nlohmann/json。虽然使用了--recursive参数克隆但网络问题或子模块仓库的临时故障可能导致某些子模块没有成功拉取。解决方案首先尝试强制更新所有子模块在 QGC 源码根目录下打开终端执行git submodule sync --recursive git submodule update --init --recursive --force这会让 Git 重新同步并拉取所有子模块。手动补全缺失库如果上述命令仍无法解决问题就需要手动处理。以nlohmann/json为例错误信息会指出是哪个库缺失。访问 QGC 的 GitHub 仓库在libs目录下找到对应的子模块。直接访问该子模块的 GitHub 页面例如https://github.com/nlohmann/json。根据 QGC 源码中.gitmodules文件记录的该子模块的提交哈希commit hash在子模块仓库中切换到对应的版本通常是一个较旧的稳定版本。下载该版本的源代码可使用Download ZIP功能解压后严格按照源码中预期的目录结构将文件复制到 QGC 源码树的对应位置。例如nlohmann/json应该位于qgroundcontrol/libs/libevents/libevents/libs/cpp/parse/nlohmann/目录下。3.4 错误四Java API 过时警告/错误错误现象在构建的后期当处理 Android 资源或打包时可能会看到大量关于“使用了已过时或不推荐的 API”的警告甚至在某些严格模式下会升级为错误导致构建失败。问题根源QGC 4.4 代码库中使用的某些 Android Gradle 插件或依赖库的 API与当前 Android SDK 构建工具如我们使用的 31.0.0的较新环境不兼容。这通常不是代码错误而是 API 生命周期的正常演进。解决方案对于警告通常可以忽略它们不影响最终 APK 的生成。但如果 Gradle 构建因此失败我们需要在 QGC 的安卓构建配置中抑制这些警告。定位到 QGC 源码中的安卓构建配置文件。通常是android/build.gradle文件。在android代码块内添加或修改compileOptionsandroid { compileSdkVersion 31 // 确保与 platforms;android-31 对应 ... compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } }如果问题依然存在可以尝试在gradle.properties文件中如果没有则在安卓目录下创建添加一行允许使用过时 APIandroid.useAndroidXtrue android.enableJetifiertrue # 忽略过时 API 警告 android.allowDeprecatedApistrue注意修改构建脚本需要谨慎最好在修改前备份原文件。这些修改旨在绕过构建障碍理论上不会影响应用的核心功能。4. 部署、调试与进阶实战成功编译出 APK 只是第一步。将其部署到真实设备或模拟器并确保功能正常运行才是最终目标。4.1 连接安卓设备与虚拟设备AVD真实设备在设备的“开发者选项”中启用“USB 调试”。使用 USB 数据线连接电脑。Windows 可能需要安装对应设备的 USB 驱动程序。在命令提示符中运行adb devices应能看到设备列表。在 Qt Creator 的“设备”列表中设备也应出现。安卓虚拟设备AVD如果你在安装 Android SDK 时安装了emulator包可以使用 Android SDK 自带的 AVD Manager 创建虚拟设备。在 Qt Creator 中你也可以通过工具-外部-Android-Android 设备管理器来创建和管理 AVD。建议创建一个基于x86_64架构的系统镜像并启用硬件加速如 Intel HAXM以获得更好的性能。4.2 在 Qt Creator 中部署与运行确保在项目-运行设置中已正确配置了“部署配置”。通常 Qt Creator 会自动添加一个“部署到 Android 设备”的步骤。在左下角的设备选择器中选择你已连接的安卓设备或正在运行的 AVD。点击绿色的“运行”按钮或 CtrlR。Qt Creator 会执行以下操作构建项目如果代码有变动。将 APK 安装到目标设备。启动应用程序。如果一切顺利你将在设备上看到 QGC 的启动画面和主界面。4.3 与无人机模拟器联调测试在没有真实无人机的情况下可以使用软件在环SITL模拟器来测试 QGC 的连接与控制功能。常用的组合是ArduPilot SITL配合MAVProxy作为地面站代理。基本联调步骤启动 ArduPilot SITL在模拟器中启动一架无人机例如四旋翼arducopter。启动 MAVProxyMAVProxy 会默认在 UDP 端口 14550 上监听来自地面站的连接。配置 QGC 连接在安卓设备上运行的 QGC 中进入连接设置。添加一个 UDP 连接。关键点在于需要填写运行 SITL 和 MAVProxy 的电脑的 IP 地址而不是127.0.0.1localhost。端口号通常为14550。配置网络桥接针对安卓模拟器如果你的 QGC 运行在安卓模拟器如夜神模拟器、蓝叠中模拟器默认使用 NAT 网络模式与宿主机网络隔离。你需要将模拟器的网络模式改为“桥接模式”Bridged这样模拟器会获得一个与宿主机同网段的 IP 地址两者才能通信。在 MAVProxy 中转发数据在 MAVProxy 控制台中使用命令将数据转发到安卓设备或模拟器的 IP 地址和端口例如 14550output add 192.168.1.100:14550其中192.168.1.100应替换为安卓设备/模拟器的实际 IP。完成这些步骤后QGC 应该能接收到来自模拟器的 MAVLink 数据显示无人机状态并允许你进行任务规划、参数调整等操作。这个过程能有效验证你编译的 QGC APK 核心通信功能是否正常。4.4 生成签名 APK 与性能优化生成签名 APK为了在非开发设备上安装或发布到应用商店你需要对 APK 进行签名。使用 JDK 的keytool生成一个密钥库keytool -genkey -v -keystore my-release-key.keystore -alias my-key-alias -keyalg RSA -keysize 4096 -validity 10000在 Qt Creator 的项目-构建 Android APK设置中指定该密钥库文件、别名和密码。以Release模式重新构建Qt Creator 将生成一个已签名的 APK。构建优化并行编译在项目-构建步骤-Make的额外参数中可以添加-jN例如-j8其中 N 是你的 CPU 核心数以加速编译过程。清理构建如果遇到奇怪的链接错误尝试执行构建-清理项目然后删除整个build-*目录再重新构建。查阅构建日志Qt Creator 的“编译输出”面板包含了所有细节。遇到错误时仔细阅读错误信息上方的几行输出往往能找到更根本的原因。环境搭建和问题排查是开发者的一项基本功。面对 QGC 这样复杂的跨平台项目耐心和系统性思维尤为重要。每一次成功的构建不仅意味着一个可运行的程序更代表着你对其技术栈的理解又深入了一层。希望这份指南能成为你探索 QGroundControl 安卓开发世界的一块坚实垫脚石。