Ubuntu 22.04下PX4开发环境搭建全攻略：从架构到仿真实战

想当初我在 Ubuntu 22.04 上第一次搭 PX4 开发系统，前前后后折腾了整整一个周末。不是编译报错，就是 Gazebo 黑屏，要么就是 QGroundControl 连不上仿真固件。现在回头看，大部分问题其实都出在同一个地方：对这套系统由哪些组件组成、各自怎么协作，没有一个清晰的整体概念。

所以这篇文章我打算换个讲法。不照着官方文档逐行翻译，而是从整体架构开始，把从零到能跑起无人机仿真的每一步都拆开揉碎，把我踩过的坑和解决思路全部写出来。如果你正准备在 Ubuntu 22.04 上搭建 PX4 开发环境，或者搭到一半卡住了，这篇文章应该能帮你省下不少时间。

1. 搭建 PX4 开发系统前，先把这几件事想清楚

1.1 为什么我选 Ubuntu 22.04

PX4 官方文档对 Ubuntu 版本的支持一直比较明确，长期支持版（LTS）是首选。Ubuntu 22.04 LTS 对应的 PX4 主分支和 v1.15 系列都是官方 CI 的主力测试平台，依赖库版本、编译工具链的兼容性都验证得比较充分。

相比 Ubuntu 20.04，22.04 的优势在于 Python 3.10 和 CMake 版本更符合新版 PX4 的要求，尤其是编译 Gazebo Garden 仿真环境时，很多依赖在 20.04 上需要手动源码编译，而在 22.04 上直接 apt 装就行。我没有选择更新的 24.04，原因很现实：PX4 当前不少工具链脚本对新版本系统的适配还不完整，我不想把时间花在排查系统兼容性上。

一句话总结：如果你是为了踏实开发，选 22.04 是当前风险最低的路径。

1.2 PX4 开发系统的完整技术栈

很多人以为“PX4 开发系统”就是装一个软件，其实它是一个组合体。我先给你画一下脑图：

• PX4 固件本身：也就是 PX4-Autopilot 源码仓库，编译后产生真正的飞控程序。
• 仿真环境：通常是 Gazebo，提供虚拟世界和无人机模型。PX4 负责飞控逻辑，Gazebo 负责物理和视觉。
• 地面站：最常用的是 QGroundControl，用来查看飞行状态、参数、日志，也可以通过它手动起飞和控制。
• 外部通信接口：MAVLink 协议负责 PX4 与地面站/外部程序通信，同时有 MAVSDK 等开发库供二次开发使用。

这四层缺一不可。大多数搭建失败的情况，不是 PX4 本身编译不过，而是某一层之间版本不匹配。

1.3 磁盘、内存和网速：硬性条件清单

在动手之前，请先检查一下机器配置。我实测的底线如下：

• 磁盘剩余空间：至少 20GB。PX4 源码和子模块就有好几个 GB，编译中间文件再加几个 GB，Gazebo 模型库和地面站又要占用不少空间，这一步千万别省。
• 内存：建议 8GB 以上。4GB 内存跑 Gazebo 加编译会非常痛苦，swap 再大也顶不住。
• CPU：没什么硬性要求，但核心数越多编译越快。8 核机器首次全量编译大约十几分钟，2 核的老机器可能要跑近一个小时。
• 网络：主要是拉取 GitHub 仓库和子模块时对网速敏感，建议在网络稳定的时段操作。

注意：如果你的机器以前装过 ROS、Gazebo 或者其他机器人开发环境，系统里可能已经存在一些 PX4 依赖。这不一定全是好事，版本冲突就是从这里开始的。后面我会专门讲怎么排查。

2. 基础环境准备：从空白系统到能跑编译

2.1 系统安装与换源

Ubuntu 22.04 的安装过程这里不展开讲，网上教程很多。我只提醒几个要点：安装时选择“最小安装”可以减少不必要的桌面软件；磁盘分区建议把/home独立出来，方便以后重装系统不丢代码；用户名最好不要带中文和空格，否则后面有些工具会出奇怪的问题。

装好系统后，第一件事是更新软件源。如果你在国内，这一步很关键，因为默认源的速度实在太慢。修改/etc/apt/sources.list，把archive.ubuntu.com和security.ubuntu.com替换成可用的镜像源，然后在终端执行：

sudo apt update && sudo apt upgrade -y

顺手把几个基础工具装上：

sudo apt install -y git vim curl wget htop net-tools

这一步没有技术含量，但能避免后面写代码、调试、传文件时到处缺工具。

2.2 安装 PX4 官方依赖脚本

PX4 官方仓库里提供了一个自动化脚本，用来安装编译所需的几乎所有依赖。路径是Tools/setup/ubuntu.sh，但直接去 GitHub 上拉这个脚本再执行，不如先把整个仓库拉下来更稳妥。所以我建议先克隆源码，再回头跑脚本。

不过如果你已经确定要用某个版本分支，也可以先跑脚本再拉代码，顺序不关键。这里我先按依赖前置的方式讲。

PX4 官方文档推荐的执行方式是：

bash ./PX4-Autopilot/Tools/setup/ubuntu.sh

这个脚本会安装一堆东西：CMake、Ninja、Python 相关包、Gazebo、OpenCV 等。它还会尝试安装 ARM 嵌入式工具链，哪怕你只做仿真不需要它。整个执行时间非常长，期间需要多次输入密码，建议留出半小时以上的空闲时间。

如果你不想用全自动脚本，也可以手动装核心依赖。这是我验证过的最小集合：

sudo apt install -y \ cmake ninja-build exiftool \ python3-pip python3-empy python3-toml python3-numpy python3-yaml \ pyqt5-dev-tools \ libeigen3-dev libopencv-dev \ protobuf-compiler \ libgz-math7-dev \ libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \ gstreamer1.0-plugins-bad gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ gstreamer1.0-tools

其中 GStreamer 相关的是仿真画面推流和录屏用的，缺少会在运行时报警告。OpenCV 和 Eigen 是 PX4 内部模块的硬依赖。Ninja 比 Make 编译速度快很多，必装。

2.3 Python 环境：最容易踩坑的环节

Ubuntu 22.04 自带的 Python 是 3.10，理论上满足 PX4 要求，但坑在于 Python 包版本。

PX4 编译过程会调用 Python 脚本处理一些代码生成和配置工作，对empy、jinja2、numpy、tomo这几个库的版本比较敏感。最常见的报错是module 'em' has no attribute 'Raw'，这个我在 6.1 节会详细讲。

我这里直接给出最稳妥的安装方式：

sudo apt install -y python3-empy python3-jinja2 python3-yaml python3-numpy pip3 install --user toml empy==3.3.2 pyros-genmsg setuptools

有两点特别提醒：

• 不要用pip3 install empy装最新版，最新版是 4.x，PX4 现在兼容性最好的是 3.3.2。
• 不要全局sudo pip3 install，容易污染系统 Python 环境。加--user装到用户目录就够用了。

另外，建议把~/.local/bin加入 PATH，否则一些 pip 安装的命令行工具找不到：

echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc source ~/.bashrc

3. 拉取 PX4 源码与首次编译

3.1 源码获取与子模块完整拉取

PX4 项目使用了很多子模块（submodule）。如果你只克隆主仓库而忘记拉子模块，编译的时候会报各种头文件找不到的错误。

标准操作是：

git clone https://github.com/PX4/PX4-Autopilot.git --recursive cd PX4-Autopilot git submodule update --init --recursive

--recursive参数第一次克隆时就会把子模块一起拉下来，这一步非常耗时，因为子模块里有大量第三方库。

如果你已经克隆了主仓库但忘了带--recursive，或者子模块部分失败，用下面命令修复：

git submodule sync --recursive git submodule update --init --recursive

关于网络问题，我在 6.3 节专门写。

3.2 选择正确的版本分支

这是一个很多人忽略的细节：PX4 的版本分支决定了你后面用哪个仿真器、哪个地面站版本。

我建议分两类情况：

• 追求稳定、跟着教程走：选 v1.15 系列正式版分支。
• 想尝鲜、做最新功能开发：用 main 分支，但要接受文档滞后和依赖更新的风险。

切换分支的命令很简单：

git checkout v1.15.4 git submodule update --init --recursive

注意切换分支后一定要重新拉一次子模块，否则子模块还停留在旧分支对应的版本上，编译时会出现莫名其妙的不一致。

3.3 首次编译 SITL 仿真固件

先明确一下概念：SITL（Software In The Loop）是指飞控代码直接在电脑上以进程形式运行，用仿真器提供虚拟传感器数据。我们做开发调试时最常用的就是 SITL，不需要任何硬件。

首次编译的完整命令：

cd PX4-Autopilot make px4_sitl

这个命令会编译飞控固件本体。如果你的机器内存较小，可以用单核编译避免 OOM：

make px4_sitl -j2

-j后面的数字是并行编译线程数，一般设为 CPU 核心数的 1.5 倍左右最快。首次编译建议别用-j直接拉满，避免内存不够被系统杀掉。

编译完成后，终端会显示固件信息和可用的仿真指令提示。此时 PX4 固件本体已经就绪。

3.4 编译速度与增量编译优化

编译速度快慢，主要看三件事：磁盘类型、CPU 核心数和并行参数。

如果你用的是机械硬盘，强烈建议把 PX4-Autopilot 放到固态硬盘上。实测同样的机器，SSD 比 HDD 编译速度快三倍不止。原因很简单，编译过程要频繁读写大量小文件，机械硬盘的随机 IO 性能是瓶颈。

增量编译是另一个提效重点。比如你只改了一个模块的代码，用：

make px4_sitl

它会自动检测改动并重新编译受影响的部分，通常几十秒就能完成。但如果你改了顶层 CMakeLists，可能触发全量编译，这个属于正常情况。

还有一个技巧：如果只是想跑仿真，并不需要每次跑make px4_sitl后再单独启动 Gazebo，直接make px4_sitl gz_x500（v1.15）或make px4_sitl gazebo-classic（v1.14）一条命令就能把固件和仿真器都带起来。这样省掉不少手动启动的功夫。

4. 仿真器选型与搭建

4.1 Gazebo Classic 还是 Gazebo Garden

这是 PX4 在 Ubuntu 22.04 上最容易让人迷茫的地方，因为版本换代了。

• v1.14 及更早版本：默认搭配 Gazebo Classic（版本 11 左右）。安装源是packages.osrfoundation.org。
• v1.15 及之后版本：默认转向 Gazebo Garden，同时仍然保留对 Gazebo Classic 的支持。

我个人的建议是：如果你刚接触 PX4，直接跟 main 分支或 v1.15 走，用 Gazebo Garden；如果你主要参考旧教程，那用 v1.14 配 Gazebo Classic 反而省事。最怕的就是两个版本的东西混着装，环境变量互相干扰，到时候 Gazebo 起不来都不知道是谁的锅。

4.2 安装仿真器与初始化环境变量

用官方脚本自动装的环境，一般已经把 Gazebo 装好了。但如果依赖脚本中途失败，或者你想手动装，我分别说一下。

如果你用 v1.14，需要装 Gazebo Classic：

sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" > /etc/apt/sources.list.d/gazebo-stable.list' wget https://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add - sudo apt update sudo apt install -y gazebo11 libgazebo11-dev

如果你用 v1.15 / main，装 Gazebo Garden：

sudo apt install -y gz-garden

装好之后，PX4 编译生成的仿真启动脚本会帮你设置大部分环境变量。但手动启动仿真时，需要先 source 一下环境脚本：

对于 v1.15 的 Gazebo Garden：

source /usr/share/gz/gz-garden/setup.sh

对于 v1.14 的 Gazebo Classic：

source ~/PX4-Autopilot/Tools/simulation/gazebo-classic/setup_gazebo.bash

这里强烈建议把这一行加到~/.bashrc里，避免每次开终端都要手动执行。

4.3 跑通第一架无人机

一切就绪后，首次启动仿真我推荐用最简单的多旋翼模型。

v1.15 / main 分支用：

cd ~/PX4-Autopilot make px4_sitl gz_x500

v1.14 分支用：

cd ~/PX4-Autopilot make px4_sitl gazebo-classic

执行后你会看到两个窗口：终端窗口运行着 PX4 的 shell 控制台，另一侧是 Gazebo 窗口，里面有一架无人机模型。

看到类似Ready for takeoff!的日志后，说明仿真已经正常工作。此时你可以打开 QGroundControl 的地图界面，把小飞机手动切到 Guided 模式，然后切换到另一个终端用 MAVSDK 发起飞指令。关于地面站配置，下一节细说。

常见的启动失败现象是 Gazebo 窗口空白没有模型，或者 QGroundControl 里看不到飞机。这个大概率是环境变量没配好，或者是模型下载失败。问题排查集中在 6.2 节。

5. 地面站和开发工具链配置

5.1 安装 QGroundControl

QGroundControl（简称 QGC）是 PX4 生态里最常用的地面站。安装方式是 AppImage 单文件，不用编译。

下载对应版本的 AppImage 后，赋予执行权限：

chmod +x QGroundControl.AppImage ./QGroundControl.AppImage

如果启动时报缺少库，需要先装一下系统的图形依赖：

sudo apt install -y libqt5gui5 libqt5core5a libqt5network5 libqt5widgets5 libqt5svg5 sudo apt install -y libfuse2

libfuse2这个依赖在 Ubuntu 22.04 上默认没有，AppImage 依赖它运行。不少人卡在这一步，提示AppImages require FUSE to run，就是没装 libfuse2。

5.2 串口权限与 ModemManager 坑

虽然仿真环境用不到物理串口，但只要以后接 Pixhawk 或别的飞控硬件，这一步早晚要踩。

把当前用户加入dialout组：

sudo usermod -a -G dialout $USER

然后注销重新登录，或者直接重启一次。

另外要把 ModemManager 干掉，或者至少禁止它占用串口设备。这个服务会默认检测 USB 串口，把飞控误识别成调制解调器，导致地面站连接不上：

sudo apt remove modemmanager

如果不方便卸载，可以写 udev 规则禁止它操作飞控设备，但初学者直接卸载最省心。

5.3 VS Code 和 MAVSDK：让开发环境更顺手

我个人习惯用 VS Code 写 PX4 的代码。装好之后推荐装这几个插件：C/C++（微软官方）、CMake、CMake Tools、Ctrl+Shift+P 里调用CMake: Select a Kit选中 GCC。

PX4 的 CMake 配置比较特殊，直接用 VS Code 打开仓库后它会扫描很久。建议把 build 目录加到.gitignore或 VS Code 的文件排除里，否则搜索文件时会卡。

如果你打算用 Python 做无人机控制脚本，装 MAVSDK 就够了：

pip3 install --user mavsdk

装完后可以写个最简单的起飞脚本验证链路：

import asyncio from mavsdk import System async def run(): drone = System() await drone.connect(system_address="udp://:14540") print("Waiting for drone to connect...") async for state in drone.core.connection_state(): if state.is_connected: print("Connected!") break await drone.action.arm() await drone.action.takeoff() await asyncio.sleep(5) await drone.action.land() asyncio.run(run())

运行后如果小飞机正常起飞，说明 PX4、Gazebo、QGC 到 MAVSDK 这条全链路完全打通了。

6. 常见问题与排查实录

6.1 编译相关报错速查

• module 'em' has no attribute 'Raw'

这个报错 90% 是因为 empy 版本太新。解决方式就是装回 3.3.2：

pip3 install --user empy==3.3.2

• /usr/bin/env: 'python': No such file or directory

Ubuntu 22.04 默认不提供python命令，只有python3。PX4 的部分脚本写死了python，所以需要做一个软链接：

sudo ln -s /usr/bin/python3 /usr/bin/python

• Could NOT find TinyXML或者某个库找不到

通常是依赖没装全。不要一个包一个包去试，直接跑一次官方ubuntu.sh脚本，它能补齐绝大多数依赖。脚本是幂等的，多跑几次没有副作用。

我把高频编译错误整理成一个速查表：

6.2 仿真启动异常排查

Gazebo 打开后是黑屏或者没有无人机模型，这个问题的原因通常是这几类：

第一，环境变量没有 source。检查~/.bashrc是否加载了对应仿真器的 setup 脚本。可以在启动仿真的终端里执行echo $GAZEBO_MODEL_PATH，如果是空的，说明环境变量没进来。

第二，模型文件没有下载完整。Gazebo 首次运行时会从网上拉取大量模型，如果中断会导致模型缺失。清掉缓存重新拉：

rm -rf ~/.cache/gazebo

第三，PX4 模型和 Gazebo 模型对不上。比如你选的机型在 PX4 里存在，但在 Gazebo 世界里没有对应的 sdf 文件。这时候换一个常用机型试试，比如x500或iris。

还有一个隐蔽问题：如果你同时装了 Classic 和 Garden，环境变量顺序错了会导致 Gazebo 启动报版本错误。我建议只保留一套，避免混乱。

6.3 网络与子模块下载问题

这是国内开发者最容易卡住的地方。PX4 的子模块数量非常多，而且分布在不同的 GitHub 仓库，任何一个子模块拉取失败都会导致编译失败。

我的建议是分步处理。先确认主仓库完整：

cd ~/PX4-Autopilot git status

再检查子模块状态：

git submodule status

如果某个子模块显示-号，说明未初始化。逐个拉取通常比一次性update --init --recursive稳定，因为就算单个失败，不会影响其他已经拉好的。

如果你在反复拉子模块时遇到几百 MB 的文件下载超时，可以考虑调整 git 的压缩和缓冲参数：

git config --global http.postBuffer 524288000 git config --global core.compression 0

core.compression 0是关闭压缩，因为某些代理服务器对压缩响应处理不好会导致下载损坏。这两个参数在某些网络环境下能明显提升稳定性。

6.4 我的一些个人心得

最后分享几条我自己的习惯，不保证每个人都适用，但至少能少走弯路。

第一，搭建环境时不要频繁切换分支。很多人喜欢今天试 main，明天换 v1.14，结果编译缓存和子模块全部错乱，最后只能删掉整个仓库重新拉。先选定一个分支，把完整流程跑通，再考虑折腾其他版本。

第二，用官方脚本前先看一眼它要装什么。ubuntu.sh是个大而全的脚本，里面有些组件是给硬件开发和 ROS 用的。如果只做 SITL 仿真，可以接受一部分冗余，但至少要知道它改了你系统的哪些地方，将来排查问题才有方向。

第三，给“第一次编译成功”做一个备份。编译成功后，整个build目录和PX4-Autopilot仓库状态都是对的。用tar打包到一个备份盘里，以后环境搞坏了直接恢复，比重新编译省太多时间。

tar -czf px4_backup.tar.gz ~/PX4-Autopilot --exclude="*.o" --exclude="*.a"

这个备份体积不大，但能救急。我自己有一次误删了某个系统库，整个环境全乱了，最后就是靠这个备份在一小时内恢复完好的。这套环境跟着我跑过好几次项目，稳定不出幺蛾子，靠的就是这些看似笨拙但确实有用的习惯。