干无人机开发这一行的朋友应该都清楚，PX4 作为开源飞控固件的事实标准，早就不是一个“选不选”的问题，而是绕不开的基本功。我自己是从 3.x 时代开始接触 PX4 的，那时候编译环境还比较折腾，踩坑踩到怀疑人生。后来陆陆续续给团队搭了不下十次开发机，发现只要抓住 Ubuntu 版本、依赖工具链、编译顺序这几个关键点，PX4 开发环境搭建并没有想象中那么可怕。

今天这篇内容主线很明确：在 Ubuntu 18.04 上完整搭建一套 PX4 开发环境，把 QGC 地面站配好，再让 Qt Creator 接进来做代码编辑和调试。文章会覆盖 PX4 固件编译、QGC 的安装连接、Qt Creator 的工程导入与调试技巧，还会把所有我遇到过的经典报错和解决方案整理成速查表。不管你是刚开始接触 PX4 的新手，还是已经编译过几次但总是被各种环境问题打断的老手，这套流程基本都能直接照着抄。

1. 为什么是 Ubuntu 18.04 + QGC + Qt Creator

1.1 这套组合解决什么问题

先理顺三个角色的分工。PX4 是跑在飞控硬件上（或者仿真环境里）的固件代码，它的编译需要一套完整的交叉编译工具链；QGC（QGroundControl）是地面站软件，用来监控飞机状态、调参、看日志、执行任务规划。Qt Creator 则是我们用来看代码、改代码、单步调试的开发工具。

这三样东西单独拎出来都能用，但真正融入一条开发链路里才会产生质变。比如你在 PX4 的仿真环境（Gazebo）里跑一架无人机，QGC 就能实时显示姿态、位置、电池电压这些状态；你在 Qt Creator 里打断点检查某个控制算法的中间变量，QGC 那边同步看到飞行数据的反馈。日常开发里 90% 的调试点都可以在这条链路里完成，而不必频繁地烧固件、上真机。

1.2 版本选择的取舍

Ubuntu 18.04 这个版本在 PX4 官方文档里是很长一段时间的推荐 LTS 版本。原因是 PX4 的依赖库（比如 Gazebo 9、ROS Melodic、Qt 5.9）在这个系统版本上的兼容性最好，官方工具链脚本（ubuntu.sh、ubuntu_sim.sh 这些）也几乎是为 18.04 量身定做的。

当然，你完全可以用 20.04 或者 22.04，我后来也试过。但现实很骨感，很多旧工具链脚本在 20.04 上会有 Python 2 依赖失效、OpenGL 库缺失这类问题。所以我给团队搭建环境时，老实交代，最后还是回到了 18.04，省心。

QGC 这边用官方发布的 AppImage 版本就可以。这个格式的好处是免安装、免依赖，下载下来加个执行权限就能跑。Qt Creator 我用的版本比较保守，5.9 到 5.12 之间都行，不需要追求最新，稳定优先。

2. 环境准备：从裸机到编译工具链

2.1 系统安装与基础配置

系统安装这一步不展开讲，需要注意的是分区时给根目录至少留出 50GB 的空间，因为 PX4 源码加上 Gazebo 模型、编译中间产物，轻松吃掉十几个 GB。装完系统第一件事是更新软件源并且做一次系统升级：

sudo apt update && sudo apt upgrade -y

如果你在国内环境，建议顺手把 apt 源换成国内镜像源，这个操作会大幅缓解后续依赖安装的速度问题。换源有个细节：Ubuntu 18.04 的源文件是 /etc/apt/sources.list，修改前先备份，不要整个覆盖，只把 archive.ubuntu.com 和 security.ubuntu.com 替换成你选的镜像地址即可。

2.2 安装 PX4 编译依赖

PX4 官方提供的依赖安装脚本是最省事的方案。在普通用户下拉取源码，然后进入 Tools/setup 目录执行：

cd ~ git clone https://github.com/PX4/PX4-Autopilot.git --recursive cd PX4-Autopilot/ bash ./Tools/setup/ubuntu.sh

这个脚本会自动安装 cmake、ninja-build、python 依赖、arm-none-eabi 交叉编译器（用于 NuttX 固件编译）以及 Gazebo 仿真器。脚本运行时间比较长，中间会要求你输入密码，还会提示安装一些 ROS 相关组件，这里你根据自己的需要选择。

有一点我必须提醒：脚本里的 git clone 步骤较多，如果你那边的网络拉取 GitHub 很慢，整个 setup 过程会卡在下载环节。我的做法是先把 PX4-Autopilot 仓库从国内镜像站整体 clone 下来再跑脚本——镜像地址我就不贴了，gitee 上搜“PX4-Autopilot”就能找到不少同步仓库，测一下哪个能 clone 通就用哪个。

2.3 为什么推荐整个脚本跑而不是一条一条装

有人习惯对着官方文档一条一条执行 apt install、pip install，结果装完了编译还是报错。原因在于 PX4 依赖特定版本的 Python 包组合，比如 empy、toml、numpy 这些，版本不匹配直接会导致 px4_utils 模块导入失败。官方脚本会把版本锁定和顺序关系都处理好，所以即使你看得懂每条命令是什么意思，也建议整个脚本直接跑，然后再针对报错单独修。

安装完成后验证关键工具是否装好：

cmake --version python3 -c "import empy; print(empy.__version__)"

如果这两条命令都能正常输出，说明基础的编译环境基本就位了。接下来可以进入固件编译环节。

3. 编译 PX4 固件：目标选择与验证方法

3.1 选择编译目标

PX4 的编译目标非常多，裸机固件有 px4_fmu-v5（Pixhawk 4）、px4_fmu-v3（Pixhawk 1）等等，仿真目标则一般是 px4_sitl、px4_gazebo。开发调试阶段，我强烈建议先从仿真目标开始。因为编译 SITL（Software In The Loop）目标不需要交叉编译器，速度也比交叉编译快得多，还能直接拉起 Gazebo 看到飞机模型。

一条命令把仿真环境跑起来：

cd ~/PX4-Autopilot make px4_sitl gazebo

第一次编译会比较久，因为要把 uORB、参数系统、控制算法等全量代码都编一遍，我的办公电脑大概需要 10 到 15 分钟。编完了会看到终端输出类似“SITL started”的日志，紧接着一个 Gazebo 窗口弹出，里面有一架四旋翼的 3D 模型。

3.2 编译错误与恢复思路

编译中间如果报错，先不要慌。最常见的是资源竞争、权限问题、某个 Python 模块版本不匹配这三类。资源竞争指的是内存不够时 make 的并行编译全部卡死，解决办法是限制并发数，比如：

make px4_sitl gazebo -j2

权限问题主要出现在下载依赖时没有写权限，或者在 /opt 下执行了需要 root 的操作。这类问题看编译日志里的 Permission denied 就能定位。

Python 模块版本不匹配是个重灾区。如果报错信息里出现“ModuleNotFoundError: No module named 'em'”或者“while executing jinja generator”，十有八九是 empy 没装好。恢复的方法是：

pip3 install empy==3.3.4

注意官方对 empy 版本有要求（一般来说 3.3.x 都行），不要随手装一个最新版，否则生成的默认参数头文件可能会有不兼容的问题。

3.3 验证编译产物的方法

当你看到Build finished successfully，编译产物默认在 build/px4_sitl_default/bin/ 目录下。验证方式有两种：一是仿真起来后，在 QGC 里看到无人机出现在地图上；二是命令行里用 listener 查看 uORB 话题。例如在运行仿真的终端里输入：

listener vehicle_attitude

能刷出 attitude 数据就说明消息系统在正常工作。这个手段在后续开发中也很常用，因为它是确认某个算法模块是否在顶层调度里跑起来的最快方式。

4. QGC 地面站安装与连接实战

4.1 下载安装 QGC

QGC 地面站安装几乎没有门槛。直接访问 QGC 的官方网站（qgroundcontrol.com）或者 GitHub releases 页面，下载最新版 Linux AppImage 文件。下载后：

chmod +x QGroundControl.AppImage ./QGroundControl.AppImage

如果操作系统缺少必要的图形依赖，会报错打不开，先装一遍基础库：

sudo apt install libqt5gui5 libqt5waylandclient5 libqt5waylandcompositor5 wayland-protocols

装完再启动 QGC。第一次打开会自动初始化地面站，界面里勾选默认设置就行，不需要额外改配置就能连接仿真。

4.2 连接仿真环境与真机端口差异

仿真环境下，QGC 默认监听 UDP 14557 端口，而 PX4 SITL 会在本机往这个端口发送 MAVLink 消息。所以你只要把 gazebo 仿真跑起来，QGC 一般会自动识别到无人机。识别成功后左上角会有一个飞行器图标，点击进去可以看到姿态、GPS、电池信息，地图上也会出现飞机当前位置。

如果是连接真机，走 USB 线接到飞控的 USB 口即可。这时候有一个高频坑：QGC 里显示 No connected vehicle。排查顺序是：

• 先用lsusb确认系统识别到硬件
• 再检查 /dev/ttyACM0 是否存在，注意可能不是 0，可能是 ACM1
• 然后确认用户是否在 dialout 组里，不在的话执行sudo usermod -a -G dialout $USER后重新登录一次

这一步操作完基本就能识别到了。真机连接时切勿直接插上飞控就飞，先看右上角的固件版本和参数是否和当前源码版本一致，避免 QGC 自动上传旧版本参数把设定值搞乱。

4.3 QGC 的常用操作与调参技巧

QGC 地面站不是只看状态的工具，它还是个强大的调参器。常用的几个地方分别是：飞行前检查页（看传感器校准状态）、参数页（搜索并修改 PX4 参数）、日志下载页（拉取 ulog 飞行日志）。这里分享一个调参经验：改参数前先按一次 Reboot，让飞控以新参数重新启动；然后一次只改一个参数，改完立刻在日志里看响应曲线。这样出了问题你才能精准知道是哪一项参数引起的。

5. Qt Creator 环境配置与调试技巧

5.1 安装 Qt Creator 与工具链配置

Qt Creator 的安装方式有两种。最简单的是 apt 直接装：

sudo apt install qtcreator

这个版本通常足够用。如果你偏爱新版界面，可以到 Qt 官方下载页面拿 Qt Online Installer 只选择 Qt Creator 组件安装，不用装一大堆无关模块。给团队做环境时，我一般用 apt 版，稳定、少折腾。

安装完成后开启 Qt Creator，进入“工具”->“选项”->“Kits”，确认编译器一栏里有 gcc/g++，CMake 一栏里能自动检测到系统 cmake。如果 CMake 列表是空的，点手动添加，把路径填到 /usr/bin/cmake 即可。

5.2 导入 PX4 工程的正确姿势

打开 Qt Creator 后，选择“打开文件或项目”，定位到 PX4-Autopilot/CMakeLists.txt。导入时 Qt Creator 会让你选择构建目录和构建参数，这一步不要默认一路下一步。PX4 的顶层 CMakeLists 会把各个模块统一组织起来，但你如果不指定编译目标，默认行为很可能无法编出可执行的 SITL 产物。

我的做法是：先不配置 Kit，导入完成后在“项目”面板里点“Build Settings”，把 CMake 参数改成：

-DCMAKE_BUILD_TYPE=RelWithDebInfo

然后构建目录指到 build/qtcreator，等 CMake 解析完成，在“构建”菜单里选择“构建项目”就能看到编译输出。

需要说明的是，Qt Creator 直接对 PX4 全量构建的速度不如命令行 make 快，因为中间层数太多。所以我的习惯是：日常编辑用 Qt Creator，编译和仿真用终端命令行，只有需要打断点调试算法时才在 Qt Creator 里构建。这是一种比较舒服的分工。

5.3 断点调试 PX4 进程

Qt Creator 的调试功能对 SITL 仿真非常友好。先在“项目”面板的运行设置里，把可执行程序路径指到仿真二进制文件，例如：

~/PX4-Autopilot/build/px4_sitl_default/bin/px4

然后在运行参数里加上启动参数，标准的一组是：

-d ~/PX4-Autopilot/build/px4_sitl_default/etc -s sitl

设置完成后，启动调试会话，在源码里打断点。比如想观察mc_pos_control_main.cpp里的位置控制输出，直接跳转到那一行打个断点，运行到断点时就可以查看局部变量的实时值。这个能力是纯命令行开发完全没法替代的，特别是排查控制算法里“某个状态量异常跳变”这类问题时，单步跟数据非常有帮助。

5.4 在 Qt Creator 里写 QML 插件

QGC 支持用 QML 写自定义分析工具和面板，如果打算深度定制 QGC，Qt Creator 的 QML 查看器也值得一用。做法是在 Qt Creator 里直接打开你的 QML 文件，它会自动进入 QML 调试模式，可以实时查看组件树和属性值。QML 调试有个小坑：如果 QGC 是自己编译的，启动时要加-qmljsdebugger参数才能被 Qt Creator 识别，否则只能编辑代码，没法在线看效果。

6. 仿真环境联动：一条龙到多窗口调试

6.1 完整跑一次 SITL + QGC + 代码调试

三件套搭建好后，我建议你完整跑一次联合调试流程，因为这才是以后开发工作的常态。先把仿真启动起来：

cd ~/PX4-Autopilot make px4_sitl gazebo

等 Gazebo 弹出飞机模型后，启动 QGC，这时 QGC 会自动发现仿真飞机。然后在 Qt Creator 里对你要调试的函数加断点，再单独启动一个终端里的调试会话。注意这里有个顺序问题：QGC 和 Qt Creator 的调试进程会同时占用同一套 MAVLink 消息流，如果 QGC 连接正常而 Qt Creator 那边看不到飞机状态，多半是因为端口被占用了。解决办法是在跑 Qt Creator 调试前，先关掉 QGC 的某个连接视图，或者调整仿真端的端口映射，别让两边抢同一个端口。

6.2 地图定位与航点任务的验证

联合调试中最常见的一个场景是验证航点任务。在 QGC 里画一个航线（例如一个矩形），点击上传任务，仿真飞机应该按照航点顺序依次飞。这个时候如果代码里面对任务状态机的处理有 bug，飞机会出现“到了第一个点就悬停不动”的情况。排查步骤是：先在 QGC 地图上看航点编号是否激活，再到源码里 commander 模块和 navigator 模块处打日志，看消息是否正常流转到导航模块。这么一套流程下来，日常 80% 的逻辑调试都能解决。

6.3 多机仿真与集群调试的思路

如果你的开发工作涉及多机协同，PX4 也支持多无人机 SITL。做法是启动多份仿真实例，每个实例用不同的端口。QGC 默认只能连接一个 MAVLink 流，需要额外加-mavlink-endpoint参数或者用 mavlink 转发工具。这个我还没有用到很深入，但基本思路是：给每架仿真飞机分配独立的端口，再用 QGC 的“多个飞行器”视图同时监控。这一块如果后面有时间，我打算单独写一篇。

7. 高频问题与避坑速查表

7.1 编译与启动阶段

整理一下我在搭建环境和日常开发中踩得最频繁的坑，方便你复制到笔记里备用。

7.2 硬件连接与调试阶段

这里再补充一个经验：如果你用虚拟机（比如 VMware 或 VirtualBox）装 Ubuntu 来做这个环境，务必把虚拟机的“3D 加速”选项打开，否则 Gazebo 和 QGC 的渲染经常有问题。另外虚拟机内存不要低于 6GB，分辨率建议用 1920x1080 以上，不然 QGC 界面在低分辨率下按钮会挤在一起，操作体验很差。

最后说几句实在话

从装系统到可以正常跑仿真，我第一次花了整整一个周末，中间踩的坑比这篇文章里写的还要多。后来搭多了才发现，这个环境的最大价值不是“能编译”，而是“能调试”。有了 Qt Creator 的断点能力，你才能看得见控制算法内部的数据流动；有了 QGC 的地图与日志，你才能把“飞机行为异常”和“代码逻辑里的哪一行”对应起来。

给新手的最后建议是：环境搭好以后别急着改代码，先原样编译一次、仿真一次、在 Qt Creator 里打断点走一遍，把整个流程的“手感”建立起来。这个过程越熟练，后面查问题的时候就越快。还有一点，源码目录尽量放在 home 下，不要放中文路径下，PX4 的构建脚本对非 ASCII 路径支持不是很好。这些都是我实打实摔出来的经验，你照着做能少走不少弯路。