我最早接触PX4那会儿最头疼的不是飞控逻辑有多复杂而是环境半天搭不起来。当时照着网上各种帖子折腾Ubuntu、装依赖、拉源码每一步都可能踩坑最后好不容易编译通过又要折腾QGC地面站和IDE调试。尤其是用Qt Creator看代码、打断点调试PX4源码网上能说清楚的教程很少。这篇文章我就把在Ubuntu 18.04上从零搭建PX4开发环境的完整过程写出来覆盖固件编译、仿真运行、QGC连接以及Qt Creator工程配置尽量把你可能遇到的问题一次性讲透。这篇内容适合两类人看一类是刚接触PX4、想在PC上跑SITL仿真的新手另一类是已经能编译固件但想在Qt Creator里调试PX4代码、搞懂飞控内部逻辑的进阶学习者。我会顺着实际的搭建顺序走每一步都讲清楚为什么要这么做而不是只甩一串命令让你复制。1. 搭建PX4开发环境之前先搞懂这套工具链是怎么协作的1.1 PX4固件、QGC地面站、Qt Creator各自扮演什么角色很多新手上来就急着敲命令结果环境装到一半就乱了。我建议先花两分钟把工具链的关系理清。PX4是一个开源的飞控固件项目平时我们说的“编译PX4”实际是把PX4 Firmware源码编译成能在仿真环境或真实飞控硬件上运行的固件。在Ubuntu上最常见的编译目标是px4_sitl_default也就是把PX4编译成计算机上的仿真进程配合Gazebo或jMAVSim模拟出飞机姿态、传感器数据让我们的地面站和控制代码像操作真机一样跟它交互。QGCQGroundControl是PX4官方推荐的地面站软件主要负责飞控状态显示、地图规划、参数调整、航迹规划等。在仿真阶段QGC会从UDP端口接收PX4仿真进程发出来的MAVLink遥测数据。这样你在QGC上看到的高度曲线、姿态角变化其实都来自仿真数据。Qt Creator则是开发调试工具。PX4源码体量不小纯用vim看代码会很难受而Qt Creator提供了一套良好的CMake工程支持可以索引整个PX4源码、跳转定义、打断点调试。把PX4源码导入Qt Creator之后你才算是真正进入了“能看能改能调”的阶段。1.2 版本匹配Ubuntu 18.04和PX4固件分支的兼容性现在PX4官方对新版本Ubuntu的支持越来越激进比如Ubuntu 20.04、22.04甚至24.04都有对应的工具链支持脚本。但总有人因为各种原因还在用Ubuntu 18.04比如实验室里的旧电脑、公司内部指定系统或者是照着老教程学习。Ubuntu 18.04对应的PX4版本建议控制在v1.13.x及以前往上更新版本的PX4代码和依赖库可能对CMake、Python版本有更高要求编译时容易出幺蛾子。我习惯这样处理先确定自己用的PX4版本分支再阅读根目录下的README.md或Tools/setup/目录里的脚本说明。比如PX4 v1.12和v1.13版本的编译工具链要求差异并不大Ubuntu 18.04都能支持。等环境跑通之后再考虑要不要切换新版本。另外要强调的是Ubuntu 18.04自带的Python版本是3.6PX4相关的很多工具链脚本对Python版本比较敏感。如果后续要跑Tools/setup/ubuntu.sh脚本会自动安装一系列依赖但有时候会因为网络问题或软件源版本过旧而失败。后面我会专门讲这个坑。2. Ubuntu 18.04系统层面的准备换源、依赖安装和Python环境2.1 先更新软件源和基础系统包我见过太多人在还没更新系统的情况下直接装PX4依赖结果装到一半报找不到某些包。正确的流程是先把软件源切到国内镜像源如果你的网络访问官方源速度慢或者至少确保系统包索引是最新的。在Ubuntu 18.04上软件源配置文件是/etc/apt/sources.list。如果你用的是清华源或阿里源把原来的archive.ubuntu.com和security.ubuntu.com替换成对应镜像地址就行。换完源之后执行sudo apt update sudo apt upgrade这一步能避免很多“找不到软件包”的问题。比如PX4编译依赖里有个exiftool它的Ubuntu软件包名是libimage-exiftool-perl如果你没更新软件源可能就搜不到这个包。2.2 PX4官方依赖脚本与手动安装的取舍PX4官方在源码仓库的Tools/setup/目录下提供了依赖安装脚本ubuntu.sh。理论上一条命令就能装完所有依赖bash ./Tools/setup/ubuntu.sh但实际跑起来经常会遇到两个问题一是脚本会下载安装Miniconda用于管理Python环境二是它默认安装的Gazebo版本可能与你Ubuntu 18.04系统自带的库冲突。所以我自己更倾向于半自动方式先手动安装基础编译依赖再用脚本补全特殊依赖。基础编译依赖包括sudo apt install -y \ git zip cmake build-essential ninja-build \ genromfs exiftool astyle libncurses5-dev \ libxml2-utils vim-common libgstreamer1.0-dev \ libgstreamer-plugins-base1.0-dev \ protobuf-compiler libprotoc-dev libprotobuf-dev \ python3-pip python3-dev python3-venv这里ninja-build是PX4推荐使用的构建工具编译速度快、错误信息可读性好。cmake需要确保版本不低于3.10.2Ubuntu 18.04自带版本通常满足但如果你之前手动装过别的版本要注意路径冲突。2.3 Python环境的处理避免pip和系统Python打架Ubuntu 18.04的默认Python 3.6比较老PX4的一些工具链脚本虽然能兼容但如果你用pip给系统Python盲目装包很容易破坏系统环境。我建议用虚拟环境隔离。创建一个专门的虚拟环境目录比如~/px4_venvpython3 -m venv ~/px4_venv source ~/px4_venv/bin/activate pip install --upgrade pip pip install pyulog pymavlink这里pymavlink是编译和仿真中可能会用到的MAVLink工具库pyulog用于解析ULog飞行日志。在编译PX4源码时部分脚本会调用python3如果你在虚拟环境里编译需要确保解释器指向正确。但另一个麻烦是Gazebo和其他工具链脚本可能依赖系统Python而不是虚拟环境。所以我的做法是编译PX4时在虚拟环境下执行如果遇到脚本找不到系统库再退出虚拟环境用系统Python编译。这种“优先隔离、必要时灵活切换”的方式比强求一个固定解要省心很多。3. PX4固件源码的拉取、子模块初始化和第一次编译3.1 使用git clone拉取PX4源码PX4固件源码托管在GitHub上。由于历史原因很多初学者喜欢直接下载ZIP包这样后期很难管理子模块也无法切换分支。正确方式是用git clonemkdir -p ~/src cd ~/src git clone --recursive https://github.com/PX4/PX4-Autopilot.git -b v1.13.2这里我给了一个具体的版本号v1.13.2。如果你不确定用哪个版本可以先不指定-bclone默认主分支但主分支的代码在Ubuntu 18.04上可能会遇到CMake版本不够的问题。所以建议第一次搭建时选一个明确版本。--recursive参数会同时拉取所有子模块。PX4有大量子模块比如固件依赖的mavlink库、各种硬件驱动、图传协议库等。如果网络状态不太好子模块拉取容易中断导致后期编译报找不到头文件。3.2 子模块更新的标准操作有时候即使用了--recursive子模块依然可能因为网络问题没有拉全。判断方法很简单进入PX4源码目录执行git submodule status如果有子模块路径前面是负号-说明这个子模块没有正确初始化如果是空格说明正常同步。针对失败的子模块单独更新git submodule update --init --recursive这个命令可以反复执行它会自动补录缺失的子模块。在GitHub连接不稳定的情况下可以试试改用深度较小的clone比如git clone --recursive --depth 1只克隆最新一次提交体积会小不少但要注意这样无法切换历史版本。3.3 编译PX4 SITL仿真固件第一次编译PX4我建议直接编译仿真目标因为不需要连接真实硬件也不涉及交叉编译环境。进入PX4源码目录执行cd PX4-Autopilot make px4_sitl_default gazebo这条命令做了三件事先配置CMake构建目录再编译SITL固件最后启动Gazebo仿真环境。第一次编译耗时比较长取决于CPU性能通常在10分钟到30分钟之间做好心理准备。编译过程中如果提示缺少某些依赖比如GStreamer库就回头检查第2节的基础依赖是否装完。还有一种很常见的提示是cmake版本过低这时需要手动升级CMake不能只依赖apt安装。3.4 编译完成后的启动验证编译完成后终端会打印一段启动信息最后会拉起Gazebo界面里面出现一架多旋翼模型。这时候PX4仿真进程已经在后台运行默认监听UDP 14540端口而QGC需要通过UDP 14550端口接收遥测数据。有人会在这里发懵明明编译成功了为什么QGC连不上原因在于PX4仿真进程启动时只默认打开了连接仿真器的本地端口并不会自动把数据转发给QGC。通常QGC运行在同一台计算机上时会自动绑定UDP 14550监听端口而PX4仿真进程默认也会向127.0.0.1:14550发送遥测数据所以正常情况下QGC是可以直接连上的。如果连不上到头来往往不是端口配置问题而是QGC的版本、系统防火墙或者AppImage执行权限出了问题。4. QGroundControl安装及与SITL仿真的连接4.1 下载与安装QGCQGC官方提供的是AppImage格式的Linux可执行文件。下载地址在QGC官网选择Ubuntu版本的.AppImage文件。下载完成后首先要给它可执行权限chmod x QGroundControl.AppImage然后点击运行或通过命令行启动./QGroundControl.AppImage注意QGC的AppImage依赖系统的FUSE库。Ubuntu 18.04默认可能没装或者装了但版本不匹配。如果双击没反应先到终端执行看报什么错。如果提示libfuse.so.2找不到执行sudo apt install libfuse2这个问题在Ubuntu 18.04上比较典型因为我遇到过很多次而且网上很多人卡在这一步。还有一个更隐蔽的坑QGC为了读取USB飞控设备通常需要加入dialout用户组否则后续连接真实飞控时会提示没有权限打开串口。即使你当前只是做仿真我也建议提前执行sudo usermod -a -G dialout $USER然后注销重新登录让用户组生效。4.2 QGC与SITL仿真之间的连接配置当你把PX4仿真跑起来再打开QGC时QGC会自动发现仿真飞控界面右上角会显示连接状态为“Simulation”。如果没连上先检查PX4仿真终端是否还在运行再查看QGC的通信配置。QGC的通信配置在“应用设置-通信连接”里可以看到默认的UDP设置。PX4 SITL仿真时默认通讯链路是角色IP地址端口PX4仿真进程发送遥测数据127.0.0.114550QGC接收遥测数据0.0.0.014550QGC发送控制指令127.0.0.114540其中14540是QGC向PX4发送指令的端口PX4仿真进程会监听这个端口。如果你自己在代码里改过MAVLink配置就要核对这几个参数是否一致。常见问题是用QGC连接真实飞控时切换到串口模式后忘改回UDP模式导致重新做仿真时始终连不上。这时候去“通信连接”里把串口连接删除只保留UDP再重新启动QGC问题基本就解决了。4.3 QGC在纯仿真场景下的使用技巧既然环境已经搭起来我建议在连接上QGC后试几个关键功能在“飞行计划”里规划一条航线然后切到“飞行”页面把模式改成“自动任务”飞机会按规划路径飞行。仿真时飞机不会真的飞出去而是在Gazebo里模拟物理效果包括姿态变化、传感器噪声、风速干扰等。如果你想更深入验证PX4逻辑还可以在QGC的“分析工具”里查看姿态、气压计、加速度计等数据曲线。这些曲线本质上来自PX4的传感器模拟模块通过MAVLink发送给QGC和真实飞控的数据链路是一样的。理解了这条链路之后调试真实飞行时也会更快上手。5. 在Qt Creator中导入PX4源码并进行代码调试5.1 Qt Creator的版本选择与安装Qt Creator是一个独立的IDE也可以和Qt库一起安装。针对PX4开发我们可以只安装Qt Creator不安装完整的Qt SDK这样体积小、环境干净。在Ubuntu 18.04上你可以通过apt安装老版本的Qt Creatorsudo apt install qtcreator不过这个版本可能比较旧。另一个选择是去Qt官网下载安装器在安装向导里勾选Qt Creator组件同时勾选Qt 5.12或以上版本的桌面库。因为我可能在后期还会用Qt开发一些地面站工具所以更推荐官方安装器一次性把Qt Creator和Qt库都装好。安装完成后打开Qt Creator在“工具-选项-环境-系统”里确认CMake路径是系统里的CMake。PX4编译会创建一个构建目录这个目录里保存编译缓存和中间文件后续我们所有修改和调试都基于这个构建目录。5.2 在Qt Creator中导入PX4源码PX4本身是一个CMake项目Qt Creator可以直接识别和导入。打开Qt Creator选择“文件-打开文件或项目”进入PX4源码目录选择根目录下的CMakeLists.txt文件。导入过程中Qt Creator会询问构建方式。这里不要选qmake要选CMake。然后配置Kit时编译器需要选择与PX4兼容的GCC版本。Ubuntu 18.04自带的GCC 7基本够用如果你之前装过GCC 8或更高版本也可以选但要注意保持和终端编译时一致的编译器避免两套构建结果不一致。配置完成后Qt Creator会开始加载CMake缓存这个过程也需要一段时间。加载完成后左侧的“项目”视图会展示整个源码目录结构你可以很方便地搜索文件、查看类定义、跳转符号。5.3 配置构建套件和运行参数PX4并不像普通Qt程序那样直接点击运行就启动它需要特定环境变量。在Qt Creator里运行PX4需要设置自定义环境脚本或添加运行参数。一种简单方式是借用PX4源码里自带的启动脚本。比如在终端编译时make px4_sitl gazebo会调用一系列启动步骤底层执行的命令通常可以拆解为make px4_sitl_default ./Tools/gazebo_sitl.sh在Qt Creator里我们可以把构建目标设置为px4_sitl_default然后在“运行”设置里添加一个自定义可执行文件指向PX4构建目录下的px4可执行文件。运行参数可以参考Tools/setup_gazebo.bash里设置的参数主要是指定Gazebo模型路径、世界文件路径和仿真端口。不过说实话在Qt Creator里直接点运行启动整个Gazebo仿真链路不是最省事的做法。我更推荐的方式是先用终端启动Gazebo仿真环境让PX4进程跑起来再用Qt Creator以调试模式附加到PX4进程这样断点才能稳定命中。具体做法是在终端里执行make px4_sitl_default gazebo等仿真启动后在Qt Creator里选择“调试-开始调试-附加到运行中的进程”找到名为px4的进程附加之后就可以在代码里打断点了。这种方式的好处是不用处理复杂的运行环境变量调试体验也更接近真实场景。5.4 添加断点、单步执行和变量监视当你附加到PX4进程后打开src/modules/mc_pos_control/MulticopterPositionControl.cpp这类核心控制代码在比如update()函数里打个断点再让QGC控制飞机起飞或切换模式你就会发现程序会停在断点处。此时你可以在“变量”窗口观察各个参数值比如期望姿态、当前位置、速度误差等。这对于理解PX4的控制逻辑特别管用。比如看_current_position和_target_position之间的差值能直观感受到位置控制环在做什么。有一点要注意PX4定时循环任务的执行频率非常高位置控制循环通常是250Hz到1000Hz如果你随意打断点可能因为停顿时间过长导致Gazebo仿真报超时。建议在调试时先把仿真暂停或者选择不那么频繁执行的模块比如任务状态机的条件分支打断点会比在紧耦合控制环路里打断点更好用。6. 编译和联调中的常见问题从报错信息到最终解决6.1 虚拟内存不足导致Gazebo启动失败Gazebo仿真非常吃内存。我在一台4GB内存的旧笔记本上跑PX4 SITL启动Gazebo后经常直接卡死或闪退。这时候检查系统内存free -h如果内存占用接近上限先把浏览器、其他IDE关掉再试。还可以调整Gazebo的物理步长参数降低传感器更新频率减少计算压力。但这个属于优化范畴建议还是换一台至少8GB内存的电脑进行日常调试。6.2 “px4: command not found”和PATH变量问题编译完成后终端里直接输入px4找不到命令通常是因为没有执行环境初始化脚本。PX4的make命令启动仿真时会自动添加构建目录到PATH但如果你手动运行px4需要先执行source Tools/setup_gazebo.bash source /usr/share/gazebo/setup.sh这两条命令会设置GAZEBO_MODEL_PATH、GAZEBO_PLUGIN_PATH等环境变量。很多人把PATH配置搞混然后烧录进系统配置文件导致每次打开终端都需要重新手动设置非常折腾。我建议把常用的环境变量写进~/.bashrc里但要控制好先后顺序避免被其他脚本覆盖。每次修改完~/.bashrc后记得执行source ~/.bashrc。6.3 编译时出现“Failed to locate package”或“could not find package”这类报错多发生在依赖安装阶段。比如编译时提示缺少GStreamer库但Ubuntu 18.04默认源里对应包名可能是libgstreamer1.0-dev和libgstreamer-plugins-base1.0-dev和PX4文档里的包名差别不大但如果软件源没更新就会找不到。解决办法是回到第2节的依赖安装确保所有包都装齐。另外要注意protobuf库版本PX4编译时会用到protoc编译器如果你的系统里同时存在多个版本的protobuf可能会导致生成的C头文件不一致出现莫名其妙的编译错误。稳妥做法是用apt统一安装sudo apt install protobuf-compiler libprotoc-dev libprotobuf-dev并且不要轻易在/usr/local下手动编译安装更高版本的protobuf。6.4 Qt Creator调试时断点无效或源码不匹配这类问题常见于调试时使用了错误的构建目录或者源码目录配置有误。比如你在终端里用make编译但Qt Creator里配置的是另一个构建目录那么调试时看到的源码行号和可执行文件里的调试信息可能不一致断点自然无效。我的做法是统一构建目录在Qt Creator里导入工程时手动指定CMake构建目录为/home/用户名/src/PX4-Autopilot/build/px4_sitl_default和终端编译使用同一个目录这样就避免了双份构建结果互相覆盖、缓存冲突的问题。还有一个细节PX4很多模块默认编译为优化版本调试时变量值会被优化掉或者跳变。如果想获得更好的调试体验可以在CMake配置里增加--debug选项或者修改cmake/px4_impl.mk等构建配置关闭-O2优化。不过这样做会增加固件体积和仿真负载我一般只在需要深入定位算法问题时才这么做。6.5 QGC无法识别USB飞控设备这个问题在从仿真切到真实飞控时特别常见。电脑明明通过USB连接了Pixhawk飞控但QGC就是看不到设备。先检查设备节点是否存在ls /dev/ttyACM0如果有设备节点但QGC没有连接通常是当前用户不在dialout组里。还有可能是调制解调器管理器ModemManager抢占了USB串口权限在终端执行sudo systemctl stop ModemManager sudo systemctl disable ModemManager这个步骤在不少Linux系统上是连接Pixhawk的隐藏前置条件我在Ubuntu 18.04和20.04都遇到过类似情况。7. 最后的实操体会这套环境我前前后后搭过不下五次每次在别人的机器上重装时依然会遇到一些新问题但总的来说只要把握住三条主线就不会偏先准备系统和依赖再编译PX4并跑通仿真最后才是配置QGC和Qt Creator做联调。很多人一上来就想着用Qt Creator调试PX4结果连仿真都没跑起来反而到处碰壁。如果你只想用PX4做地面站软件测试那QGC和仿真环境就够用了不一定非要配置Qt Creator。但如果你打算深入PX4源码比如修改控制算法、添加新的自定义模块那Qt Creator是值得花时间配好的工具。我个人一般先用终端跑通常规编译再用Qt Creator附加调试这样既能快速验证代码逻辑又不影响仿真环境的稳定性。最后分享一个小技巧如果你在Ubuntu 18.04上编译不同版本PX4固件建议给每个版本单独建编译目录比如build_px4_v1.13、build_px4_v1.12这样免得CMake缓存互相干扰。真要调试某个版本时直接切分支重新配置构建目录会比在同一个目录下反复删缓存要省事很多。这套流程跑通之后后续无论是接真实飞控还是做半实物仿真都会顺畅不少。