第一次在 Ubuntu22.04 下搭 ROS2 与 PX4 仿真环境我断断续续折腾了一周。期间遇到的大部分问题不是命令本身有多复杂而是版本搭配、依赖下载、Gazebo 反复崩溃这些教程里根本不会写的东西。这篇文章把我最终跑通的全流程、每一步为什么这么选、以及踩过的坑完整记下来给想在本地搞 PX4 二次开发、offboard 控制、SLAM 导航的朋友一份可以直接照做的参考。整个流程最终实现的效果是在 Gazebo 里跑起一架四旋翼仿真模型PX4 固件在 PC 上以 SITL 模式运行ROS2 Humble 通过 MicroXRCEAgent 桥接获取飞控的所有状态话题并且可以用 Rviz2 实时看到飞机的姿态和轨迹。这套环境搭完后面做算法开发和调试基本不会再被环境问题绊住。1. 动手前必须想清楚的版本选型与整体架构1.1 为什么是 Ubuntu22.04 ROS2 Humble PX4 v1.14版本选型是整个搭建过程里最容易被忽视、却最容易决定成败的一步。很多人一上来就装最新版本结果某个依赖对不上翻遍 GitHub Issue 也找不到答案。我的建议直接锁死下面这套组合组件推荐版本说明Ubuntu22.04 LTS长期支持版生态最稳ROS2Humble与 Ubuntu22.04 对应的 LTS 版本PX4v1.14.3稳定版支持 ROS2 原生桥接GazeboClassic 11默认安装资料最丰富桥接组件MicroXRCEAgentPX4 与 ROS2 之间的通信代理这套组合的好处在于Ubuntu22.04 和 ROS2 Humble 都是 LTS 版本生命周期长第三方包几乎都能直接装上PX4 v1.14.3 是当前教程兼容性最好的稳定版既支持老牌的 Gazebo Classic也支持新一代 Gazebo。新手不要碰 PX4 main 分支也不要急着上 Ubuntu24.04 ROS2 Jazzy生态还在磨合期很多工具链和教程都对不上。1.2 三个核心组件各管什么很多入门者容易把 PX4、ROS2、Gazebo 当成一个整体来装出问题后完全不知道是谁的锅。这里我用一个直白的类比来解释PX4 是四旋翼的“飞控大脑”负责姿态解算、位置控制、传感器融合这些底层逻辑。ROS2 是“信息总线”负责在无人机和上层算法之间传递消息。Gazebo 是“训练场”提供物理仿真环境让 PX4 以为自己在真实飞。那 MicroXRCEAgent 又是什么PX4 内部用的是一套叫作 uORB 的轻量通信机制ROS2 用的是 DDS 分布式通信协议两者语言不通。MicroXRCEAgent 就像个翻译官把 uORB 消息转换成 ROS2 话题再把 ROS2 下发的指令翻译回 uORB。没有它PX4 和 ROS2 就像两个各说各话的人。1.3 先选好承载方式双系统、虚拟机还是 WSL2在动手装之前还有一个容易忽略的决策点这套环境跑在哪里。三种方式我都试过直接说结论虚拟机VMware/VirtualBox最推荐新手。安装简单快照功能简直是环境搭建的后悔药系统搞崩了秒回滚。代价是性能损耗和 GPU 渲染能力弱Gazebo 画面会卡但纯跑算法验证完全够用。双系统性能最接近原生Gazebo 流畅度最好。缺点是需要处理磁盘分区和引导问题如果电脑是工作主力机风险略高。WSL2启动快和 Windows 文件互访方便配合 WSLg 能显示图形界面。但 Gazebo 的 OpenGL 渲染在 WSL2 里经常出问题后面接真实飞控时 USB 串口还得用 usbipd-win 映射多一层额外配置。我的建议是如果你只是学习 PX4 和 ROS2虚拟机是第一选择如果要做视觉 SLAM 这类吃性能的工作直接原生 Ubuntu 或双系统。2. ROS2 Humble 安装三步走与两个高频故障点2.1 换 apt 源与基础环境准备安装 ROS2 之前先把 Ubuntu 源换成国内镜像。这一步不是必须的但对于经常卡在 apt 下载上的人来说能省下大量时间。备份源文件然后根据你的 Ubuntu 22.04 版本选择合适的镜像源。标准的 Ubuntu 22.04 源文件在/etc/apt/sources.list如果发现这个路径不存在去/etc/apt/sources.list.d/下找.sources文件用同样的方式处理。换源后执行sudo apt update sudo apt upgrade -y把系统基础包更新到最新。升级过程中如果出现内核更新建议重启一次再往下走避免后续编译时出现莫名其妙的库版本冲突。2.2 添加 ROS2 软件源并安装 HumbleROS2 的官方源地址是 packages.ros.org。先把公钥和源信息写进系统sudo apt install curl gnupg lsb-release -y sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null sudo apt update然后一键安装桌面版完整套件sudo apt install ros-humble-desktop python3-argcomplete ros-dev-tools -y这里我明确建议装ros-humble-desktop而不是ros-humble-ros-base。desktop 版带上了 Rviz2、Gazebo、demo 节点等一整套可视化工具后面做联合仿真验证时全部用得上。base 版只有通信核心省不了几个空间却会让你后面反复补包。安装完成后把环境变量写进 bashrc这样每次开终端不用手动 sourceecho source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc2.3 rosdep init 失败的根治方法这是 ROS2 安装过程中第一大坑。执行sudo rosdep init时经常卡在下载配置文件那一步因为 rosdep 需要从 raw.githubusercontent.com 拉取一个配置文件而这个域名在国内网络环境下极不稳定。rosdep 的作用是自动解析功能包的依赖项纯仿真环境里用它的时候不多但只要你后面打算手动编译 Nav2、Cartographer 这类源码包就必须把它搞定。我推荐的根治方案是直接用国内社区维护的rosdepcpip3 install rosdepc sudo rosdepc init rosdepc updaterosdepc在功能上完全替代了rosdep不需要改任何现有命令习惯。如果你还是想用官方 rosdep可以尝试在网络状况较好的时段反复运行但说实话没必要在这上面死磕工具的目的是解决问题而不是折腾自己。2.4 用 ROS2 小乌龟验证安装ROS2 安装是否成功最直观的验证方式就是跑一下官方小乌龟ros2 run turtlesim turtlesim_node新开一个终端启动键盘控制ros2 run turtlesim turtle_teleop_key然后用ros2 topic list、ros2 topic echo /turtle1/pose这些命令观察话题通信。当你在键盘上按方向键乌龟在窗口里移动同时pose话题在持续输出位置信息时说明 ROS2 的发布订阅机制已经正常工作了。这一步虽然简单但能确认通信链路没有问题避免后面排查联合仿真时来回怀疑环境。3. PX4 固件获取与编译源码版本、子模块与磁盘空间3.1 拉取指定版本的 PX4 源码PX4 的源码在 GitHub 上官方仓库是 PX4/PX4-Autopilot。拉取时注意两点必须加--recursive参数拉取子模块必须指定 tag 而不是拉 main 分支。git clone https://github.com/PX4/PX4-Autopilot.git --recursive -b v1.14.3如果不加--recursive克隆下来的源码缺少大量子模块编译时绝对报错。如果你已经漏掉了这一步可以进目录后执行git submodule update --init --recursive补上。国内网络环境下 clone 这个仓库比较折磨仓库本体加所有子模块有 2GB 左右。几点实测经验clone 中断后重新执行git fetch或git submodule update系统会基于已有数据续传绝大多数情况下不用删掉重来。如果卡在某个子模块上反复失败可以先想办法从可信渠道单独获取该子模块仓库再放进对应目录。不要在 clone 的同时开一堆占带宽的应用PX4 的仓库体积大网络抖动时容易超时。3.2 磁盘空间评估别让编译卡在 99%很多人在 PX4 编译阶段翻车不是代码有问题而是磁盘满了。PX4 源码加编译产物加上 Gazebo 模型和其他工具链整套环境至少预留 30GB 空间。加上 ROS2 本身占用的 8GB 左右我给的最低建议是 50GB。动手前先看空间df -h如果根分区不够可以把 PX4-Autopilot 克隆到其他有空间的挂载点上。编译过程中 PX4 会在源码目录下生成build/文件夹里面的中间文件很大但不建议直接删掉重编后续增量编译会依赖它。3.3 用官方脚本一次性装齐编译依赖PX4 官方提供了 Ubuntu 环境自动配置脚本这是最省心也最不容易错的方式cd PX4-Autopilot bash ./Tools/setup/ubuntu.sh这个脚本会处理 GCC、CMake、Ninja、Python 依赖、Gazebo、QGroundControl 依赖等一堆东西。运行过程中需要输入 sudo 密码整体耗时 15 到 30 分钟中途如果某个 apt 源 404 或网络超时脚本会报错退出。我的经验是脚本报错后先别慌着手动逐项补装再看一遍报错信息。绝大多数情况是某个 apt 源不完整把源修好重跑一遍脚本就过了。脚本本身是幂等的重复运行不会重复安装已装好的包。3.4 编译 SITL 仿真固件依赖装好后编译 PX4 的 SITLSoftware In The Loop仿真固件cd ~/PX4-Autopilot make px4_sitl gazebo-classic这条命令的意思是编译 SITL 固件并启动 Gazebo Classic 仿真器。第一次编译会拉取 Gazebo 模型数据库耗时在 10 到 20 分钟之间。编译完成的标志终端出现pxh提示符同时 Gazebo 窗口弹出一架四旋翼模型。如果你看到类似gazebo: command not found的报错说明 ubuntu.sh 脚本在安装 Gazebo 时出了问题回到上一步修复。不要试图手动安装 Gazebo 来解决PX4 对 Gazebo 的版本和插件路径有特定要求手动装往往缺插件。4. 启动仿真与 MicroXRCEAgentPX4 和 ROS2 的通信桥梁4.1 正确启动顺序与端口约定PX4 SITL 和 MicroXRCEAgent 的启动顺序其实没有硬性要求两个进程会通过 UDP 自动重连。我的习惯是先启动 PX4再启动 Agent因为这样 PX4 控制台里能看到连接建立的过程。启动 PX4cd ~/PX4-Autopilot make px4_sitl gazebo-classic看到pxh提示符后另开一个终端编译并启动 MicroXRCEAgent。Agent 可以装在系统任意位置我习惯放在~/tools下统一管理git clone https://github.com/eProsima/Micro-XRCE-DDS-Agent.git cd Micro-XRCE-DDS-Agent mkdir build cd build cmake .. make sudo make install sudo ldconfig安装完成后直接运行MicroXRCEAgent udp4 -p 8888启动成功后会进入一个带日志输出的终端界面。PX4 默认的 Micro XRCE-DDS 配置就是通过 UDP 8888 端口通信如果看到类似Client connected的日志说明桥接已经建立。4.2 QGroundControl 地面站让飞机飞起来联合仿真环境里最好配一个 QGroundControlQGC地面站它不仅能让你直观看到无人机状态还承担着一个关键功能给仿真飞机解锁和发送起飞指令。去 QGC 官网下载对应系统的 AppImage 文件然后chmod x QGroundControl.AppImage ./QGroundControl.AppImageQGC 启动后会自动发现本机的 SITL 仿真实例通过 UDP 14550 端口接收 MAVLink 数据。地面站界面上能看到无人机的姿态、电池、GPS 等信息。飞起来的方法在 QGC 右上角点击起飞按钮确认解锁并推油门Gazebo 里的四旋翼会徐徐起飞并悬停在两米左右高度。这一步特别重要因为很多人在后面ros2 topic echo时发现数据没有变化其实是飞机一直没解锁姿态和位置数据恒为零。4.3 如果机器性能不够怎么办Gazebo 是整套环境里最吃资源的组件物理引擎要实时计算图形渲染还要占用 GPU。如果你发现 Gazebo 窗口卡到没法看有两个处理办法第一个办法是降低 Gazebo 的图形负载关闭 QGC 的 3D 视图在 Gazebo 菜单里关掉光照阴影和反锯齿。第二个办法是如果实在带不动图形界面PX4 支持无头模式运行启动时加环境变量PX4_HEADLESS1 make px4_sitl gazebo-classic这样 Gazebo 不会弹出窗口但物理仿真照常运行同时 MicroXRCEAgent 和 QGC 都能正常连接。远程开发机或低配虚拟机建议直接用这种模式性能和稳定性反而更好。5. 联合仿真验证从 topic 列表到 Rviz2 三维可视化5.1 用 ros2 topic list 确认桥接成功所有组件都跑起来后接下来就是验证链路是否真的通了。在任意终端执行source /opt/ros/humble/setup.bash ros2 topic list如果 MicroXRCEAgent 连接正常你会看到一长串以/fmu/out/和/fmu/in/开头的话题。/fmu/out/是 PX4 向外发布的飞控状态/fmu/in/是 ROS2 向 PX4 下发的指令。看到这些话题说明 uORB 到 DDS 的转换链路已经打通。如果你只看到rosout等系统默认话题说明桥接可能有问题。排查顺序是先确认 MicroXRCEAgent 日志中有没有客户端连接记录再确认 PX4 控制台是否报过 XRCE 相关错误最后检查系统防火墙是否放行了 UDP 8888 端口。5.2 读 fmu/out 话题理解飞控数据流向链路打通后找一个核心话题看看数据ros2 topic echo /fmu/out/vehicle_odometry --once你会看到类似这样的输出position字段是无人机在仿真世界坐标系中的三维位置quaternion字段是四元数形式的姿态描述。很多人第一次看四元数会懵这里解释一下四元数是一个四维向量用来表示三维空间中的旋转相比欧拉角它不会出现万向锁问题。PX4 输出的是[w, x, y, z]格式其中w是旋转的标量部分。如果你想看直观的欧拉角不推荐直接转换Rviz2 里的 TF 显示比人工读四元数直观得多。5.3 用 Rviz2 可视化飞机姿态与轨迹Rviz2 是 ROS2 最常用的数据可视化工具。启动它ros2 run rviz2 rviz2首先在左侧面板点 Add添加 TF 显示。TF 是 ROS2 里的坐标变换树添加后你能看到飞机的机体坐标系轴随着 Gazebo 里的模型一起转动。然后再 Add 一个 Odometry比如 Odometry 显示控件把话题设置为/fmu/out/vehicle_odometry你就能看到飞机飞行时画出的轨迹线。这时候回到 QGC 里控制飞机前后左右飞行Rviz2 中的轨迹会同步更新整个数据链路形成了一个完整闭环。顺便说一句等这套可视化玩明白了再去研究 PX4 姿态解算里的卡尔曼滤波推导会直观得多。你在 Rviz2 里看到的每一次姿态变化背后就是一套融合了IMU、GPS和气压计数据的完整算法链。5.4 飞机起飞后原地打转甚至翻机怎么办仿真中经常遇到一个现象飞机是飞起来了但四旋翼原地打转或者刚离地就翻机。出现这种情况时先不要怀疑代码或算法绝大多数是仿真初始化的问题。把 Gazebo 窗口关掉PX4 控制台退出然后重新执行make px4_sitl gazebo-classic让整个仿真环境干净地重启一遍。PX4 的 SITL 会随机生成初始偏移量极少数情况下模型与地面接触的瞬间碰撞检测出问题重置一次就能解决。另外注意起飞操作不要用键盘手动推太大的油门最好的方式是用 QGC 的 Takeoff 按钮飞控会自动控制油门输出尽量避免人为制造失控输入。6. 最容易翻车的细节清单与排查链路6.1 磁盘、内存、显卡硬件资源要心里有数整套环境跑起来后PX4 编译、Gazebo 物理仿真、ROS2 消息交互、Rviz2 渲染同时进行8GB 内存是及格线16GB 才能流畅。编译阶段最吃资源建议临时关掉浏览器和 IDE给编译器留足内存。如果 Gazebo 卡得无法忍受先看是不是虚拟机VMware 默认的显卡虚拟化性能很弱可以尝试调整虚拟机设置的 3D 加速开关。如果是物理机重点检查显卡驱动是否正常。注意不要为了跑 Gazebo 去折腾英伟达闭源驱动在绝大多数情况下开源驱动已经够用。6.2 版本混用带来的噩梦我遇到过不少用户是在装好 ROS2 Foxy 的旧系统上直接升级安装 Humble结果两个版本的环境变量互相冲突ros2命令时好时坏。ROS2 的版本管理比较脆弱不同版本的大版本不能共存。另一个经典问题是用 Ubuntu 24.04 装 ROS2 Jazzy然后照着 Humble 教程跑很多命令看着差不多报错却完全对不上。建议严格按本文开头的版本组合来等把整个流程走通一遍再考虑升级也不迟。6.3 Python 包与 rosdep 的国内环境适配PX4 和 ROS2 编译过程中会用到大量 Python 包。国内环境下强烈建议配置 pip 源和 ROS 工具链的国内镜像具体做法pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simplerosdep 的问题在前面已经说过直接用rosdepc替代官方工具。这一步能避免在依赖解析环节反复卡住。显卡驱动和 CUDA 在纯仿真阶段完全不需要不要为了追求性能提前装 CUDAPX4 的 SITL 仿真用不到反而可能和系统库冲突。6.4 端口占用问题MicroXRCEAgent 默认监听 UDP 8888QGC 监听 UDP 14550。如果 Agent 启动时报地址被占用用下面命令查一下ss -ulpn | grep 8888找到占用进程后结束它或者修改 Agent 的端口参数重新绑定。如果你修改了端口PX4 端也要用param set同步修改 XRCE_DDS_CFG 配置否则两边端口对不上连接永远建不起来。6.5 WSL2 环境下的额外注意事项在 WSL2 里跑这套环境是可行的但有几个 WSL2 特有的拦路虎。首先是图形界面问题较新的 Windows 版本自带 WSLgGazebo 窗口能直接弹出如果你的版本比较老就得安装 VcXsrv 并设置 DISPLAY 环境变量。其次是性能问题WSL2 的 GPU 虚拟化依赖显卡驱动支持。我实测过WSL2 里 Gazebo 的运行流畅度比原生 Linux 差不少物理计算能跑但画面渲染经常掉帧。如果你只是想做 offboard 控制这类的纯算法验证问题不大涉及视觉仿真和点云渲染老实实装双系统吧。最后是 USB 设备问题后面接真实飞控时WSL2 识别不了 Windows 的串口需要用 usbipd-win 把设备映射到 WSL2 内部。这个步骤不难但多一层配置就多一处出错的可能。这套环境走到这里已经具备在 ROS2 里订阅 PX4 全量状态、下发控制指令、可视化仿真数据的能力。我个人实际使用中的体会是每次重装这套环境时把本文的命令整理成 shell 脚本版本号全部用变量定义能再节省小半天时间。接下来比较顺的方向是研究 offboard 控制用/fmu/in/offboard_control_mode和/fmu/in/trajectory_setpoint话题写一个简单的直线飞行程序那才是真正开始玩 PX4 二次开发的第一步。 
长河君 · 2026/9/19 6:18:49 · 阅读 1.2k Ubuntu22.04下ROS2 Humble与PX4 SITL仿真环境搭建全攻略
第一次在 Ubuntu22.04 下搭 ROS2 与 PX4 仿真环境我断断续续折腾了一周。期间遇到的大部分问题不是命令本身有多复杂而是版本搭配、依赖下载、Gazebo 反复崩溃这些教程里根本不会写的东西。这篇文章把我最终跑通的全流程、每一步为什么这么选、以及踩过的坑完整记下来给想在本地搞 PX4 二次开发、offboard 控制、SLAM 导航的朋友一份可以直接照做的参考。整个流程最终实现的效果是在 Gazebo 里跑起一架四旋翼仿真模型PX4 固件在 PC 上以 SITL 模式运行ROS2 Humble 通过 MicroXRCEAgent 桥接获取飞控的所有状态话题并且可以用 Rviz2 实时看到飞机的姿态和轨迹。这套环境搭完后面做算法开发和调试基本不会再被环境问题绊住。1. 动手前必须想清楚的版本选型与整体架构1.1 为什么是 Ubuntu22.04 ROS2 Humble PX4 v1.14版本选型是整个搭建过程里最容易被忽视、却最容易决定成败的一步。很多人一上来就装最新版本结果某个依赖对不上翻遍 GitHub Issue 也找不到答案。我的建议直接锁死下面这套组合组件推荐版本说明Ubuntu22.04 LTS长期支持版生态最稳ROS2Humble与 Ubuntu22.04 对应的 LTS 版本PX4v1.14.3稳定版支持 ROS2 原生桥接GazeboClassic 11默认安装资料最丰富桥接组件MicroXRCEAgentPX4 与 ROS2 之间的通信代理这套组合的好处在于Ubuntu22.04 和 ROS2 Humble 都是 LTS 版本生命周期长第三方包几乎都能直接装上PX4 v1.14.3 是当前教程兼容性最好的稳定版既支持老牌的 Gazebo Classic也支持新一代 Gazebo。新手不要碰 PX4 main 分支也不要急着上 Ubuntu24.04 ROS2 Jazzy生态还在磨合期很多工具链和教程都对不上。1.2 三个核心组件各管什么很多入门者容易把 PX4、ROS2、Gazebo 当成一个整体来装出问题后完全不知道是谁的锅。这里我用一个直白的类比来解释PX4 是四旋翼的“飞控大脑”负责姿态解算、位置控制、传感器融合这些底层逻辑。ROS2 是“信息总线”负责在无人机和上层算法之间传递消息。Gazebo 是“训练场”提供物理仿真环境让 PX4 以为自己在真实飞。那 MicroXRCEAgent 又是什么PX4 内部用的是一套叫作 uORB 的轻量通信机制ROS2 用的是 DDS 分布式通信协议两者语言不通。MicroXRCEAgent 就像个翻译官把 uORB 消息转换成 ROS2 话题再把 ROS2 下发的指令翻译回 uORB。没有它PX4 和 ROS2 就像两个各说各话的人。1.3 先选好承载方式双系统、虚拟机还是 WSL2在动手装之前还有一个容易忽略的决策点这套环境跑在哪里。三种方式我都试过直接说结论虚拟机VMware/VirtualBox最推荐新手。安装简单快照功能简直是环境搭建的后悔药系统搞崩了秒回滚。代价是性能损耗和 GPU 渲染能力弱Gazebo 画面会卡但纯跑算法验证完全够用。双系统性能最接近原生Gazebo 流畅度最好。缺点是需要处理磁盘分区和引导问题如果电脑是工作主力机风险略高。WSL2启动快和 Windows 文件互访方便配合 WSLg 能显示图形界面。但 Gazebo 的 OpenGL 渲染在 WSL2 里经常出问题后面接真实飞控时 USB 串口还得用 usbipd-win 映射多一层额外配置。我的建议是如果你只是学习 PX4 和 ROS2虚拟机是第一选择如果要做视觉 SLAM 这类吃性能的工作直接原生 Ubuntu 或双系统。2. ROS2 Humble 安装三步走与两个高频故障点2.1 换 apt 源与基础环境准备安装 ROS2 之前先把 Ubuntu 源换成国内镜像。这一步不是必须的但对于经常卡在 apt 下载上的人来说能省下大量时间。备份源文件然后根据你的 Ubuntu 22.04 版本选择合适的镜像源。标准的 Ubuntu 22.04 源文件在/etc/apt/sources.list如果发现这个路径不存在去/etc/apt/sources.list.d/下找.sources文件用同样的方式处理。换源后执行sudo apt update sudo apt upgrade -y把系统基础包更新到最新。升级过程中如果出现内核更新建议重启一次再往下走避免后续编译时出现莫名其妙的库版本冲突。2.2 添加 ROS2 软件源并安装 HumbleROS2 的官方源地址是 packages.ros.org。先把公钥和源信息写进系统sudo apt install curl gnupg lsb-release -y sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null sudo apt update然后一键安装桌面版完整套件sudo apt install ros-humble-desktop python3-argcomplete ros-dev-tools -y这里我明确建议装ros-humble-desktop而不是ros-humble-ros-base。desktop 版带上了 Rviz2、Gazebo、demo 节点等一整套可视化工具后面做联合仿真验证时全部用得上。base 版只有通信核心省不了几个空间却会让你后面反复补包。安装完成后把环境变量写进 bashrc这样每次开终端不用手动 sourceecho source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc2.3 rosdep init 失败的根治方法这是 ROS2 安装过程中第一大坑。执行sudo rosdep init时经常卡在下载配置文件那一步因为 rosdep 需要从 raw.githubusercontent.com 拉取一个配置文件而这个域名在国内网络环境下极不稳定。rosdep 的作用是自动解析功能包的依赖项纯仿真环境里用它的时候不多但只要你后面打算手动编译 Nav2、Cartographer 这类源码包就必须把它搞定。我推荐的根治方案是直接用国内社区维护的rosdepcpip3 install rosdepc sudo rosdepc init rosdepc updaterosdepc在功能上完全替代了rosdep不需要改任何现有命令习惯。如果你还是想用官方 rosdep可以尝试在网络状况较好的时段反复运行但说实话没必要在这上面死磕工具的目的是解决问题而不是折腾自己。2.4 用 ROS2 小乌龟验证安装ROS2 安装是否成功最直观的验证方式就是跑一下官方小乌龟ros2 run turtlesim turtlesim_node新开一个终端启动键盘控制ros2 run turtlesim turtle_teleop_key然后用ros2 topic list、ros2 topic echo /turtle1/pose这些命令观察话题通信。当你在键盘上按方向键乌龟在窗口里移动同时pose话题在持续输出位置信息时说明 ROS2 的发布订阅机制已经正常工作了。这一步虽然简单但能确认通信链路没有问题避免后面排查联合仿真时来回怀疑环境。3. PX4 固件获取与编译源码版本、子模块与磁盘空间3.1 拉取指定版本的 PX4 源码PX4 的源码在 GitHub 上官方仓库是 PX4/PX4-Autopilot。拉取时注意两点必须加--recursive参数拉取子模块必须指定 tag 而不是拉 main 分支。git clone https://github.com/PX4/PX4-Autopilot.git --recursive -b v1.14.3如果不加--recursive克隆下来的源码缺少大量子模块编译时绝对报错。如果你已经漏掉了这一步可以进目录后执行git submodule update --init --recursive补上。国内网络环境下 clone 这个仓库比较折磨仓库本体加所有子模块有 2GB 左右。几点实测经验clone 中断后重新执行git fetch或git submodule update系统会基于已有数据续传绝大多数情况下不用删掉重来。如果卡在某个子模块上反复失败可以先想办法从可信渠道单独获取该子模块仓库再放进对应目录。不要在 clone 的同时开一堆占带宽的应用PX4 的仓库体积大网络抖动时容易超时。3.2 磁盘空间评估别让编译卡在 99%很多人在 PX4 编译阶段翻车不是代码有问题而是磁盘满了。PX4 源码加编译产物加上 Gazebo 模型和其他工具链整套环境至少预留 30GB 空间。加上 ROS2 本身占用的 8GB 左右我给的最低建议是 50GB。动手前先看空间df -h如果根分区不够可以把 PX4-Autopilot 克隆到其他有空间的挂载点上。编译过程中 PX4 会在源码目录下生成build/文件夹里面的中间文件很大但不建议直接删掉重编后续增量编译会依赖它。3.3 用官方脚本一次性装齐编译依赖PX4 官方提供了 Ubuntu 环境自动配置脚本这是最省心也最不容易错的方式cd PX4-Autopilot bash ./Tools/setup/ubuntu.sh这个脚本会处理 GCC、CMake、Ninja、Python 依赖、Gazebo、QGroundControl 依赖等一堆东西。运行过程中需要输入 sudo 密码整体耗时 15 到 30 分钟中途如果某个 apt 源 404 或网络超时脚本会报错退出。我的经验是脚本报错后先别慌着手动逐项补装再看一遍报错信息。绝大多数情况是某个 apt 源不完整把源修好重跑一遍脚本就过了。脚本本身是幂等的重复运行不会重复安装已装好的包。3.4 编译 SITL 仿真固件依赖装好后编译 PX4 的 SITLSoftware In The Loop仿真固件cd ~/PX4-Autopilot make px4_sitl gazebo-classic这条命令的意思是编译 SITL 固件并启动 Gazebo Classic 仿真器。第一次编译会拉取 Gazebo 模型数据库耗时在 10 到 20 分钟之间。编译完成的标志终端出现pxh提示符同时 Gazebo 窗口弹出一架四旋翼模型。如果你看到类似gazebo: command not found的报错说明 ubuntu.sh 脚本在安装 Gazebo 时出了问题回到上一步修复。不要试图手动安装 Gazebo 来解决PX4 对 Gazebo 的版本和插件路径有特定要求手动装往往缺插件。4. 启动仿真与 MicroXRCEAgentPX4 和 ROS2 的通信桥梁4.1 正确启动顺序与端口约定PX4 SITL 和 MicroXRCEAgent 的启动顺序其实没有硬性要求两个进程会通过 UDP 自动重连。我的习惯是先启动 PX4再启动 Agent因为这样 PX4 控制台里能看到连接建立的过程。启动 PX4cd ~/PX4-Autopilot make px4_sitl gazebo-classic看到pxh提示符后另开一个终端编译并启动 MicroXRCEAgent。Agent 可以装在系统任意位置我习惯放在~/tools下统一管理git clone https://github.com/eProsima/Micro-XRCE-DDS-Agent.git cd Micro-XRCE-DDS-Agent mkdir build cd build cmake .. make sudo make install sudo ldconfig安装完成后直接运行MicroXRCEAgent udp4 -p 8888启动成功后会进入一个带日志输出的终端界面。PX4 默认的 Micro XRCE-DDS 配置就是通过 UDP 8888 端口通信如果看到类似Client connected的日志说明桥接已经建立。4.2 QGroundControl 地面站让飞机飞起来联合仿真环境里最好配一个 QGroundControlQGC地面站它不仅能让你直观看到无人机状态还承担着一个关键功能给仿真飞机解锁和发送起飞指令。去 QGC 官网下载对应系统的 AppImage 文件然后chmod x QGroundControl.AppImage ./QGroundControl.AppImageQGC 启动后会自动发现本机的 SITL 仿真实例通过 UDP 14550 端口接收 MAVLink 数据。地面站界面上能看到无人机的姿态、电池、GPS 等信息。飞起来的方法在 QGC 右上角点击起飞按钮确认解锁并推油门Gazebo 里的四旋翼会徐徐起飞并悬停在两米左右高度。这一步特别重要因为很多人在后面ros2 topic echo时发现数据没有变化其实是飞机一直没解锁姿态和位置数据恒为零。4.3 如果机器性能不够怎么办Gazebo 是整套环境里最吃资源的组件物理引擎要实时计算图形渲染还要占用 GPU。如果你发现 Gazebo 窗口卡到没法看有两个处理办法第一个办法是降低 Gazebo 的图形负载关闭 QGC 的 3D 视图在 Gazebo 菜单里关掉光照阴影和反锯齿。第二个办法是如果实在带不动图形界面PX4 支持无头模式运行启动时加环境变量PX4_HEADLESS1 make px4_sitl gazebo-classic这样 Gazebo 不会弹出窗口但物理仿真照常运行同时 MicroXRCEAgent 和 QGC 都能正常连接。远程开发机或低配虚拟机建议直接用这种模式性能和稳定性反而更好。5. 联合仿真验证从 topic 列表到 Rviz2 三维可视化5.1 用 ros2 topic list 确认桥接成功所有组件都跑起来后接下来就是验证链路是否真的通了。在任意终端执行source /opt/ros/humble/setup.bash ros2 topic list如果 MicroXRCEAgent 连接正常你会看到一长串以/fmu/out/和/fmu/in/开头的话题。/fmu/out/是 PX4 向外发布的飞控状态/fmu/in/是 ROS2 向 PX4 下发的指令。看到这些话题说明 uORB 到 DDS 的转换链路已经打通。如果你只看到rosout等系统默认话题说明桥接可能有问题。排查顺序是先确认 MicroXRCEAgent 日志中有没有客户端连接记录再确认 PX4 控制台是否报过 XRCE 相关错误最后检查系统防火墙是否放行了 UDP 8888 端口。5.2 读 fmu/out 话题理解飞控数据流向链路打通后找一个核心话题看看数据ros2 topic echo /fmu/out/vehicle_odometry --once你会看到类似这样的输出position字段是无人机在仿真世界坐标系中的三维位置quaternion字段是四元数形式的姿态描述。很多人第一次看四元数会懵这里解释一下四元数是一个四维向量用来表示三维空间中的旋转相比欧拉角它不会出现万向锁问题。PX4 输出的是[w, x, y, z]格式其中w是旋转的标量部分。如果你想看直观的欧拉角不推荐直接转换Rviz2 里的 TF 显示比人工读四元数直观得多。5.3 用 Rviz2 可视化飞机姿态与轨迹Rviz2 是 ROS2 最常用的数据可视化工具。启动它ros2 run rviz2 rviz2首先在左侧面板点 Add添加 TF 显示。TF 是 ROS2 里的坐标变换树添加后你能看到飞机的机体坐标系轴随着 Gazebo 里的模型一起转动。然后再 Add 一个 Odometry比如 Odometry 显示控件把话题设置为/fmu/out/vehicle_odometry你就能看到飞机飞行时画出的轨迹线。这时候回到 QGC 里控制飞机前后左右飞行Rviz2 中的轨迹会同步更新整个数据链路形成了一个完整闭环。顺便说一句等这套可视化玩明白了再去研究 PX4 姿态解算里的卡尔曼滤波推导会直观得多。你在 Rviz2 里看到的每一次姿态变化背后就是一套融合了IMU、GPS和气压计数据的完整算法链。5.4 飞机起飞后原地打转甚至翻机怎么办仿真中经常遇到一个现象飞机是飞起来了但四旋翼原地打转或者刚离地就翻机。出现这种情况时先不要怀疑代码或算法绝大多数是仿真初始化的问题。把 Gazebo 窗口关掉PX4 控制台退出然后重新执行make px4_sitl gazebo-classic让整个仿真环境干净地重启一遍。PX4 的 SITL 会随机生成初始偏移量极少数情况下模型与地面接触的瞬间碰撞检测出问题重置一次就能解决。另外注意起飞操作不要用键盘手动推太大的油门最好的方式是用 QGC 的 Takeoff 按钮飞控会自动控制油门输出尽量避免人为制造失控输入。6. 最容易翻车的细节清单与排查链路6.1 磁盘、内存、显卡硬件资源要心里有数整套环境跑起来后PX4 编译、Gazebo 物理仿真、ROS2 消息交互、Rviz2 渲染同时进行8GB 内存是及格线16GB 才能流畅。编译阶段最吃资源建议临时关掉浏览器和 IDE给编译器留足内存。如果 Gazebo 卡得无法忍受先看是不是虚拟机VMware 默认的显卡虚拟化性能很弱可以尝试调整虚拟机设置的 3D 加速开关。如果是物理机重点检查显卡驱动是否正常。注意不要为了跑 Gazebo 去折腾英伟达闭源驱动在绝大多数情况下开源驱动已经够用。6.2 版本混用带来的噩梦我遇到过不少用户是在装好 ROS2 Foxy 的旧系统上直接升级安装 Humble结果两个版本的环境变量互相冲突ros2命令时好时坏。ROS2 的版本管理比较脆弱不同版本的大版本不能共存。另一个经典问题是用 Ubuntu 24.04 装 ROS2 Jazzy然后照着 Humble 教程跑很多命令看着差不多报错却完全对不上。建议严格按本文开头的版本组合来等把整个流程走通一遍再考虑升级也不迟。6.3 Python 包与 rosdep 的国内环境适配PX4 和 ROS2 编译过程中会用到大量 Python 包。国内环境下强烈建议配置 pip 源和 ROS 工具链的国内镜像具体做法pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simplerosdep 的问题在前面已经说过直接用rosdepc替代官方工具。这一步能避免在依赖解析环节反复卡住。显卡驱动和 CUDA 在纯仿真阶段完全不需要不要为了追求性能提前装 CUDAPX4 的 SITL 仿真用不到反而可能和系统库冲突。6.4 端口占用问题MicroXRCEAgent 默认监听 UDP 8888QGC 监听 UDP 14550。如果 Agent 启动时报地址被占用用下面命令查一下ss -ulpn | grep 8888找到占用进程后结束它或者修改 Agent 的端口参数重新绑定。如果你修改了端口PX4 端也要用param set同步修改 XRCE_DDS_CFG 配置否则两边端口对不上连接永远建不起来。6.5 WSL2 环境下的额外注意事项在 WSL2 里跑这套环境是可行的但有几个 WSL2 特有的拦路虎。首先是图形界面问题较新的 Windows 版本自带 WSLgGazebo 窗口能直接弹出如果你的版本比较老就得安装 VcXsrv 并设置 DISPLAY 环境变量。其次是性能问题WSL2 的 GPU 虚拟化依赖显卡驱动支持。我实测过WSL2 里 Gazebo 的运行流畅度比原生 Linux 差不少物理计算能跑但画面渲染经常掉帧。如果你只是想做 offboard 控制这类的纯算法验证问题不大涉及视觉仿真和点云渲染老实实装双系统吧。最后是 USB 设备问题后面接真实飞控时WSL2 识别不了 Windows 的串口需要用 usbipd-win 把设备映射到 WSL2 内部。这个步骤不难但多一层配置就多一处出错的可能。这套环境走到这里已经具备在 ROS2 里订阅 PX4 全量状态、下发控制指令、可视化仿真数据的能力。我个人实际使用中的体会是每次重装这套环境时把本文的命令整理成 shell 脚本版本号全部用变量定义能再节省小半天时间。接下来比较顺的方向是研究 offboard 控制用/fmu/in/offboard_control_mode和/fmu/in/trajectory_setpoint话题写一个简单的直线飞行程序那才是真正开始玩 PX4 二次开发的第一步。