Ubuntu 22.04+PX4+Gazebo无人机仿真环境搭建与排错指南

项目标题点到的是Ubuntu22.04GazeboPX4 开发环境搭建看上去像一条三行命令就能糊弄过去的事但只要真在本地跑过一遍就会知道这套组合的麻烦不在装不装得上而在装上了跑不起来、跑起来连不上、连上了数值全歪。我前后在三台不同配置的机器上重复过这个流程最长的一次卡了整整两天最后发现只是一条 submodule 没拉全。所以这篇不打算给你一份复制粘贴就能成的神话教程而是把整条链路拆开每一步为什么这么做、做错了会以什么形式表现出来、怎么在十分钟内判断自己是哪一类故障。刚接触无人机仿真、想跑通第一个 SITL 实例的人可以照着走已经能跑但偶尔莫名其妙崩掉、被版本问题反复折磨的人也值得看看后面几节的排查思路。仿真环境本质上是把三件本来独立演进的东西强行捆在一起一个飞控软件栈PX4、一个负责物理和渲染的仿真器Gazebo、一个操作系统Ubuntu 22.04。三者各有各的发布节奏绑在一起就必然存在一个互相都认的版本窗口。这个窗口不宽而且每次大版本升级都会挪位置。理解这件事比记住任何一条命令都重要。1. 版本矩阵先钉死这套环境十次翻车八次是版本错配1.1 一次典型故障告诉我版本表比教程更重要我最早接触这套环境是在一块旧笔记本上系统是 Ubuntu 22.04照着某篇教程一路apt install装完 PX4 源码make px4_sitl gazebo敲下去编译跑了二十分钟然后报了一串和ignition、gz-transport相关的链接错误。当时的直觉是库没装全于是继续装装了七八个包错误变了但没消失。后来才发现真正的原因是那份教程写于更早的系统版本里面默认的仿真器是 Gazebo Classic而新版 PX4 分支已经切到了新一代的 gz-sim两套东西的库名、命名空间、启动方式全都不一样混着装只会互相污染。这个经历给我留下一个习惯动手之前先画一张版本对照表把系统版本 → PX4 分支 → 仿真器代际这三列填满确认它们属于同一代再开始装。填不出来就别动手因为后面所有报错你都无法判断是环境问题还是版本问题。1.2 一张表把 Ubuntu 22.04 能走的路线摊开在 Ubuntu 22.04 上目前实际能跑通的主要是两条路线选哪条取决于你要做什么而不是哪条更新。对比项路线 AGazebo Classic 11 PX4 v1.14路线 Bgz-simGazebo Harmonic PX4 v1.15仿真器代际老一代架构简单插件生态成熟新一代基于 ignition/gz 系列重构PX4 编译目标make px4_sitl gazebomake px4_sitl gz_x500默认机型irisx500与 ROS 2 桥接常用桥接包成熟但逐渐停更官方推荐方向长期维护老教程兼容性高网上绝大多数示例能对上低很多示例要改写显卡要求相对宽松软件渲染也能凑合对 OpenGL 版本更敏感适合谁刚入门、要跟现成课程/示例走要长期维护、打算做二次开发我的建议很直接如果你手上有一份明确的课程材料或者已有的代码仓先看它依赖哪一代跟着它走如果你是从零起步、没有历史包袱直接上路线 B省得一年后再迁移一次。最糟的选择是两条一起装因为两套仿真器会争夺同一批环境变量和端口表现出的症状会非常迷惑。1.3 开装之前先做三项体检很多人跳过这一步然后在编译阶段付出十倍的时间。三项检查五分钟搞定# 1. 确认系统版本与架构 lsb_release -a uname -m # 应为 x86_64 # 2. 确认可用内存与磁盘 free -h df -h ~ # 3. 确认显卡与 OpenGL glxinfo | grep OpenGL version编译 PX4 加仿真器的完整流程峰值内存吃到 6~8 GB 不稀奇磁盘含 submodule 和构建产物建议留 30 GB 以上。磁盘不足的表现是编译到某个大文件时突然No space left on device看起来像随机失败。另外如果glxinfo命令不存在先装mesa-utils如果 OpenGL 版本低于 3.3或者你在一台没有独显的虚拟机里后面的 Gazebo 大概率会黑屏或直接段错误这不是环境没装好是渲染后端撑不住需要提前决定是换实体机还是走无头模式。还有一条容易被忽略如果你用的是双系统务必确认时间同步和分区挂载没有异常我见过编译中途因为挂载点权限问题导致ccache写入失败的案例排查成本极高。2. 系统底座依赖装得全不全决定后面三天顺不顺2.1 官方脚本能替你做什么不能替你做什么PX4 源码树里自带一个环境安装脚本路径在Tools/setup/ubuntu.sh。这个脚本做的是把编译和仿真所需的一批包按顺序装好包括编译器、Python 工具链、各类开发库、以及仿真器本身。对新手来说这是最省事的入口cd PX4-Autopilot bash ./Tools/setup/ubuntu.sh但必须清楚它的边界。它不会替你做这几件事不会配置你的 shell 环境变量不会处理串口权限不会帮你解决模型资源的下载问题也不会在失败时告诉你哪一步失败了——它是顺序执行加set -e一旦中途某个包下载失败脚本退出前面的装好了后面的没装状态是半残的。我遇到过最坑的一次是脚本在装某个 gstreamer 插件时因为源超时退出重跑时因为前面的包已经存在而看起来成功实际缺了两三个插件直到跑仿真时视频流起不来才暴露。所以我的做法是跑脚本可以但跑完必须自己回头验证一遍关键组件是否都在。验证办法不是看脚本退出码而是直接查包状态。2.2 手动补齐那几个脚本不一定装上的包即使脚本顺利跑完下面这几类包我仍然建议手动确认一遍它们在不同版本脚本里的覆盖情况不一致sudo apt update sudo apt install -y \ git cmake build-essential ninja-build ccache \ python3-pip python3-dev python3-venv \ libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \ gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \ gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-tools \ libxml2-dev libxslt1-dev zlib1g-dev \ protobuf-compiler libeigen3-dev libopencv-dev \ geographiclib-tools libgeographic-dev \ mesa-utils逐条说下理由避免你装一堆不知道为什么装的东西。ccache是编译缓存PX4 首次全量编译大约十几到二十分钟清一次源码再编很痛苦开启缓存后二次编译能压到两三分钟这条几乎必装。ninja-build是 CMake 的替代构建后端速度和并行度都比 make 好。gstreamer 那一串是给机载相机、视频流仿真用的不装也能起飞但一旦你想接摄像头模型就会卡住。geographiclib系列负责地理坐标转换涉及全球坐标的插件会依赖它缺了的表现是仿真启动时报找不到数据集。python3-venv也值得单独提一句新版 PX4 的某些工具脚本要求独立虚拟环境系统 Python 被其它项目污染过的话会出现ModuleNotFoundError但pip list里明明有的灵异现象本质是路径冲突。2.3 用户组、串口权限与环境变量的三处必改这一节是装完看起来没事、用起来处处别扭的重灾区。第一处是串口权限。即使你只跑仿真后面接真机、接数传也用得上现在配好省事sudo usermod -aG dialout $USER改完必须重新登录或重启才生效很多人改完立刻测试发现没权限就是因为没重新登录。验证方式groups输出里应该能看到dialout。第二处是 shell 环境变量。建议在~/.bashrc里加两行把 PX4 的工具目录放进 PATH按你的实际路径改export PX4_DIR$HOME/work/PX4-Autopilot export PATH$PATH:$PX4_DIR/Tools这样后面用px4相关脚本、仿真启动脚本时不用每次都写全路径。注意别把整个构建目录塞进 PATH会让 shell 启动变慢。第三处是仿真器的资源路径。Gazebo 启动时会在若干个固定目录里找模型默认会去用户目录下找全新环境里这个目录往往是空的于是启动后模型全是灰盒子或者干脆加载失败。可以手动创建并指向随源码附带的模型目录mkdir -p ~/.gazebo/models # 若源码内附带模型资源可建立软链接指过去避免重复下载提示这一步经常被跳过症状是仿真能起来但机体显示为白色方块、或者启动日志里刷一堆模型下载失败。它不是致命错误但会让你误以为环境有问题。我还建议在正式编译前跑一次source ~/.bashrc并开一个新终端确认环境干净避免旧会话里残留的变量干扰判断。3. PX4 源码落地submodule 没拉全等于白下3.1 克隆策略与目录规划源码放哪里看着无所谓实际影响后面所有脚本的路径解析。我的习惯是在家目录下建一个统一的工程目录把源码、构建产物、日志分开放mkdir -p ~/work cd ~/work git clone https://github.com/PX4/PX4-Autopilot.git --recursive关键在于--recursive这个参数。PX4 仓库本身不大但它依赖几十个子模块仿真器适配层、第三方库、模型资源等不加这个参数克隆下来的是一个空壳编译时会报找不到某个头文件或者某个 CMake 子目录不存在。更麻烦的是这种失败往往发生在编译中途不是一开始就报容易误判。如果已经克隆完了才想起来没加参数补救方式是进目录执行cd PX4-Autopilot git submodule update --init --recursive这一步在网络条件不理想时可能需要重试几次中途失败不要紧重复执行即可git 会跳过已经拉好的部分。3.2 submodule 状态自检一条命令判断能不能编译不要靠克隆没报错来判断子模块完整。正确的判断方式是查状态git submodule status --recursive | grep -c ^-输出为0表示所有子模块都已初始化输出大于 0说明还有若干个处于未初始化状态这些就是隐患。也可以不加grep直接看行首带-的就是没拉的带的是版本和记录不一致的这个通常无害但如果你在追某个特定版本需要留意。我把这条命令当成一条编译前门禁每次换机器、换分支、切 tag 之后都跑一次。省下的排查时间远超执行成本。顺带提一个分支选择的经验如果是跟着教程学尽量切到一个明确的 tag 上而不是停在主分支。主分支每天都在动今天能编译的代码明天可能就换个编译目标名而你面对的教程是几个月前写的两边一对不上就会陷入到底是我的问题还是代码的问题的循环。git tag --list | tail -20 git checkout v1.14.3 # 示例按实际可用的稳定 tag 选择 git submodule update --init --recursive3.3 首次编译的目标语义与 ccache 生效验证编译命令看起来很简短但它背后做的事情值得说清楚make px4_sitl gazebo拆开看px4_sitl是一个构建配置对应boards/px4/sitl目录gazebo是传给这个配置的一个附加目标意思是构建完成后顺便把仿真器按指定机型拉起来。也就是说这条命令同时承担了编译和运行两件事。这解释了为什么它会一直挂在前台不返回——它在跑仿真不是你卡住了CtrlC才是退出方式。第一次编译的耗时主要花在固件本体和几十个子模块上。想先只验证编译是否通过、不启动仿真可以加后缀make px4_sitl_default # 只编译不启动仿真确认 ccache 是否真的生效看首次和二次编译的耗时差异二次编译如果还是十几分钟说明缓存没命中。常见原因是构建目录被清、或者换分支导致缓存键变化。可以显式指定缓存目录并观察命中率export CCACHE_DIR$HOME/.ccache ccache -s输出的cache hit rate是有意义的指标。我一般的做法是把CCACHE_DIR写进~/.bashrc避免不同终端下缓存分裂成好几份。注意不要为了干净养成每次编译前跑make clean的习惯。PX4 的增量构建做得不错clean会让 ccache 之外的所有中间产物消失重建成本非常高。真要清先想清楚为什么要清。3.4 编译阶段高频报错与对应根因把我在这一步见过的问题整理成一张表比逐条描述好用报错特征大概率根因处理方向找不到某头文件路径里含子模块目录名submodule 未初始化跑git submodule update --init --recursive编译到中途进程被 kill无明确错误内存不足OOM killer 介入关掉并行度make -j4或加 swapNo space left on device磁盘不足清构建目录或扩盘Python 脚本报ModuleNotFoundError虚拟环境未激活或系统 Python 被污染检查python3 -m venv与 PATH链接阶段报一堆重复符号混装了两代仿真器库卸载冲突包只保留一代编译通过但启动即崩日志几乎为空显卡/渲染问题先试无头模式验证逻辑是否通第三行和最后一行是最容易被误判的。磁盘不足看起来像随机失败因为它取决于哪个目标先写满启动即崩看起来像没装好实际是渲染后端的问题用无头模式一跑就能分辨。4. Gazebo 侧世界文件、模型库与启动链路4.1 两代仿真器的取舍不该只看新不新新人常问的一个问题是到底该用哪个。抛开版本表从实际使用角度补充几点我的观察。老一代仿真器的优势在于确定性高。它的世界文件格式、插件接口、传感器模型在过去几年基本没变你从任何一篇三年前的帖子抄来的配置大概率能直接跑。它的劣势是渲染和物理精度上限较低做视觉相关的研究时会明显吃力而且官方已经不再投入主要精力。新一代仿真器的优势是渲染质量和传感器模型更接近真实与 ROS 2 的桥接是新写的、维护活跃。劣势是文档还在补齐很多配置项的写法在老资料里查不到遇到问题只能翻源码或看示例世界文件。我的实际选择是纯飞控逻辑验证、控制算法调试用哪代都行挑你能最快跑起来的那代涉及相机、激光雷达、视觉里程计直接上新一代。不要在老一代上花大量时间搭传感器那是给自己挖坑。如果机器配置较弱还有一个折中方案不加载图形界面只跑物理和通信。这样 Gazebo 只做数值计算不占显卡对虚拟机极其友好。启动方式是在命令前加环境变量HEADLESS1 make px4_sitl gazebo无头模式下你看不到三维画面但 MAVLink 数据流、位姿、传感器话题全都是正常的配合地面站一样能完成大部分调试工作。4.2 SITL 启动脚本到底按什么顺序干活理解启动链路能让大部分起来了一半的问题变得可推理。make px4_sitl gazebo背后实际调用的是源码树里的一个 shell 脚本大致按这个顺序执行检查固件二进制是否存在不存在则先编译读取机型配置默认 iris把它转成仿真器侧需要的模型名启动仿真器进程加载指定的世界文件在其中生成对应机体模型等待仿真器把通信端口开好启动飞控进程连接仿真器提供的传感器与执行器接口飞控初始化完成后开始对外发送遥测数据。这个顺序解释了几个常见现象。比如仿真器窗口开了但飞控没起来说明卡在第 5 步通常是端口被占用或者机型名对不上。比如飞控起来了但机体不动说明第 3 步生成的模型和飞控期望的机型不匹配。比如两个进程都活着但地面站连不上问题在第 6 步之后的网络层面和第 1 到 5 步无关。知道了这个链路排查就不再是盲目重装而是先判断卡在哪一步。4.3 模型资源加载失败与离线方案仿真器启动时会去若干个目录找模型资源其中包括用户目录下的模型缓存。全新机器上这个缓存是空的首次启动会自动联网拉取。网络条件不理想时这一步会表现为启动卡住、日志里反复出现下载超时或者机体显示为一块白色方块。处理思路有两条。第一条是提前把模型资源准备好让启动时不需要联网# 创建缓存目录 mkdir -p ~/.gazebo/models # 若源码树内已附带模型可直接建立软链接避免重复下载 # ln -s /path/to/models/* ~/.gazebo/models/第二条是排查到底是模型没下载还是模型路径没配对。区别方法很简单看启动日志里有没有出现模型目录的绝对路径。如果路径指向了一个并不存在的目录那就是路径配置问题改路径比重下资源快得多。提示路径里千万不要出现中文或空格。我见过因为家目录名带中文字符导致仿真器解析路径失败的案例报错信息完全看不出和路径有关排查了一整晚。5. 飞起来之前端口、地面站连接与首次起飞验证5.1 MAVLink 端口分配表仿真跑起来后飞控会通过 UDP 对外广播遥测数据同时开放一个用于程序控制的通道。这两个通道用的是不同端口混用是新手常犯的错端口用途谁连它14550地面站遥测地面站软件、QGC 类工具14540程序控制 / 板外控制你自己写的控制程序、ROS 节点14580飞控控制台备用调试用18570部分场景下的仿真接口视配置而定地面站连接不上第一个要确认的就是它是否在监听 14550以及是否被防火墙拦了。程序控制不生效第一个要确认的是你连的是不是 14540 而不是 14550——连到地面站端口上再发控制指令飞控是不认的。5.2 连接失败的三层排查法我的排查顺序固定为进程 → 端口 → 协议从下往上每一层都能独立确认。第一层看进程。终端里两个进程是否都活着飞控进程的输出里有没有出现初始化完成的字样如果飞控进程压根没启动后面都不用看了。ps aux | grep -E px4|gz|gazebo | grep -v grep第二层看端口。用系统工具确认端口确实被监听ss -lunp | grep -E 14550|14540没有输出说明飞控没开监听问题在飞控侧配置有输出但地面站连不上问题在网络或地面站侧。第三层看协议。前面两层都正常但数据对不上通常是版本或流率问题——飞控默认下发的数据流频率可能不足以让你的程序正常工作需要显式请求数据流或者调整流率参数。这一层已经不属于环境搭建范畴但知道它存在可以避免在前两层反复折腾。5.3 解锁前的检查清单仿真环境里第一次起飞之前建议按这份清单过一遍。仿真里炸机不心疼但养成习惯对后面上真机有好处。姿态估计是否收敛机体的姿态角是否稳定有没有持续漂移或抖动传感器数据是否合理高度、气压、磁力计读数是否在合理范围有没有卡在固定值不动遥控通道是否映射正确模式切换开关能否正常切到定高、定点等模式电池电压是否被正确模拟电压过低会触发自动降落仿真里也生效解锁是否被拒绝被拒时看飞控控制台输出的具体原因不要反复硬试。姿态估计没收敛就解锁最常见的后果是一起飞就翻。这个现象在仿真里非常典型而且容易被误判为控制参数不对实际是初始几秒的估计还没稳。等十几秒再解锁问题就消失了。6. 联调与扩展ROS 2 桥接、改机型与多机仿真6.1 用 uXRCE-DDS 把 ROS 2 和飞控打通如果要做算法开发几乎一定要把飞控的数据接进 ROS 2。目前主流的做法是通过 DDS 桥接链路是飞控内置客户端 → 独立代理进程 → ROS 2 节点。第一步在系统上准备 ROS 2 环境以 Humble 为例它与 Ubuntu 22.04 是配套的。装好后确认基本可用source /opt/ros/humble/setup.bash ros2 topic list第二步准备并启动代理进程。代理是一个独立可执行程序需要单独构建构建完成后在单独终端里运行# 终端 A启动代理监听 UDP 8888 MicroXRCEAgent udp4 -p 8888第三步让飞控连上代理。仿真启动后在飞控控制台里执行uxrce_dds_client start -t udp -h 127.0.0.1 -p 8888然后用uxrce_dds_client status确认连接状态。连接成功后在 ROS 2 终端里ros2 topic list应该能看到一批以/fmu/开头的话题比如姿态、位置、电池状态等。这一步失败的高频原因有三个代理进程没起来端口没监听、飞控侧客户端没启动、以及两侧的 DDS 域配置不一致。第三个最隐蔽因为两边看起来都在正常工作就是互相看不见。遇到这种情况先确认域 ID 是否一致再往下查。6.2 改一个机型文件理解仿真配置的组织方式想换成自己设计的机体最省事的路径不是从零写而是复制一份现成的机型文件改参数。机型的定义分散在飞控侧的机型配置和仿真器侧的模型描述两处两处的名字必须对得上。改完之后编译目标里的机型名要跟着换# PX4_SIM_MODEL 指定仿真侧模型 export PX4_SIM_MODELiris make px4_sitl gazebo我踩过的一个坑是只在飞控侧加了新机型配置仿真器侧没有对应的模型文件启动后仿真器里空空如也飞控却在正常跑日志里没有任何显式错误。这种情况的判断依据是仿真器窗口里没有机体而不是看飞控日志。所以改机型时一定两边都检查。另一个经验是参数单位。质量、转动惯量、推力系数这些量在飞控配置和仿真模型里的单位约定可能不同抄参数时务必对齐单位否则会出现能飞但姿态怪异的现象非常难查。6.3 多机仿真的资源与端口规划多机仿真不是把单机启动三次那么简单端口会冲突。源码树里提供了批量启动脚本可以直接指定机数# 启动 3 架机型 iris ./Tools/simulation/gazebo-classic/sitl_multiple_run.sh -m iris -n 3每架机体占用一组端口按顺序递增。地面站连接时需要用不同的端口分别连程序控制端同理。规划好端口表比事后改配置轻松得多机体编号地面站端口程序控制端口014550145401145511454121455214542资源方面三机同仿对 CPU 的压力主要来自物理计算对显卡的压力来自渲染。如果是弱机器建议无头模式跑多机只保留必要的传感器把渲染完全省掉。我试过在一台四核机器上跑五机无头模式下勉强能实时开图形界面就直接掉到半速以下仿真时间和真实时间严重脱节——这时候你看到的所有动态响应都是不可信的。7. 反复踩到的几个坑及其根因归纳7.1 编译到一半静默退出现象是编译进行到某个大文件时进程突然消失没有任何错误信息退出码非零。看系统日志能看到内存不足相关的记录。本质是并行编译同时拉起了太多编译进程每个都要吃几百兆内存叠加起来超过物理内存系统触发保护机制杀掉进程。处理方式有三种按推荐顺序一是降低并行度make -j4甚至-j2二是加交换分区用磁盘换内存速度会慢但不会崩三是关掉其它占内存的程序。第一种最直接代价只是编译慢一点。7.2 仿真器黑屏或启动即段错误这个症状极具迷惑性因为它看起来像没装好。真正的判断方法是看它是不是在无头模式下能正常跑HEADLESS1 make px4_sitl gazebo如果无头模式一切正常问题确定在渲染层。常见原因包括显卡驱动版本过旧、OpenGL 版本不达标、在虚拟机里没有开启三维加速、或者远程连接环境下没有可用的显示。远程环境下还有一个坑是显示转发图形界面通过转发渲染时性能极差且容易崩正确做法是本地跑仿真、远程只做开发或者干脆无头。7.3 混装两代仿真器导致的诡异链接错误这条前面提过值得单独展开因为它的表现形式非常多变。装了两代仿真器之后头文件搜索路径里会同时出现两套同名但内容不同的头文件编译时命中的是哪一套取决于路径顺序于是会出现同一个报错时有时无的现象。链接阶段更麻烦符号重复定义或者符号找不到报错信息指向的库名看起来毫无关联。判断方法检查系统里是否同时存在两代仿真器的软件包dpkg -l | grep -E gazebo|gz-|ignition如果两类都有基本可以确认是混装。处理方式是明确保留一代把另一代彻底卸载干净包括它们的开发包。卸载后记得清一次构建目录因为旧的 CMake 缓存里还留着路径。7.4 切换分支后编译产物污染从一个分支切到另一个分支尤其是跨大版本切换构建目录里的缓存可能不再有效但增量构建机制不会自动感知于是编译成功了跑起来行为却很奇怪。我的做法是跨大版本切换时直接删掉构建目录重新来一次虽然多花十几分钟但避免了后面几小时的困惑。判断是否需要清目录的经验如果只是改了几行业务代码增量构建完全没问题如果动了 CMake 配置、换了仿真器代际、或者切了主版本号就老老实实清。7.5 环境变量在错误的时机被覆盖这条是我最近才总结出来的。多个项目共用一台机器时各自的setup.bash会互相覆盖环境变量导致在终端 A 里能编译在终端 B 里就报错。诊断方法是把关键变量打印出来对比env | grep -E PX4|ROS|GAZEBO|AMENT如果两个终端里输出不一致就是这个问题。解决办法是每个项目用独立终端、明确 source 顺序别在一个终端里来回切。我在多次重复搭建之后形成的固定流程现在每次换机器我的操作顺序已经固化了先查系统版本和显卡能力决定走哪条仿真器路线再装依赖装完逐项验证而不是看退出码然后克隆源码并先跑 submodule 自检通过了才开始编译编译通过先跑无头模式确认逻辑通再开图形界面最后接地面站和 ROS 2一步步加每加一层都验证一次。这套顺序最大的价值不在于快而在于每一层出问题时都能立刻定位到边界不会出现全都装好了但就是不工作这种没法下手的状态。还有一个心得值得单独说把每次成功搭建后的关键版本号、命令、以及遇到的坑记在一个文本文件里跟着工程目录一起放着。这套环境平均半年就会因为上游变更需要重新折腾一次有记录和没记录第二次的成本差三倍以上。我自己那份记录现在已经攒了十几条最短的一次重建只花了四十分钟靠的全是这些看起来毫无技术含量的备忘。