保姆级避坑指南：在Ubuntu 20.04上搞定PX4 v1.12.3 + Gazebo仿真环境
最近在折腾PX4无人机仿真环境时，发现网上大多数教程都只讲"理想情况"下的配置流程，对实际部署中可能遇到的坑点要么一笔带过，要么干脆避而不谈。作为一个刚踩完所有坑的过来人，我决定把Ubuntu 20.04下配置PX4 v1.12.3和Gazebo仿真环境时遇到的典型问题及解决方案整理成这份避坑指南。无论你是第一次接触无人机仿真的新手，还是被环境配置折磨到崩溃的开发者，这份指南都能帮你少走弯路。
1. 环境准备与PX4源码获取
1.1 系统基础环境配置
在开始之前，建议先更新系统并安装基础工具链：
sudo apt update && sudo apt upgrade -y sudo apt install -y git wget curl build-essential ninja-build关键依赖版本检查：
- GCC编译器至少需要7.5版本（
gcc --version验证） - Python 3.x（PX4 v1.12.3不支持Python 2）
- CMake 3.10+
注意：Ubuntu 20.04默认的Python 3.8和CMake 3.16完全兼容PX4 v1.12.3，无需额外处理
1.2 PX4特定版本克隆技巧
官方推荐的克隆命令是：
git clone -b v1.12.3 https://github.com/PX4/PX4-Autopilot.git --recursive但实际操作中90%的人会遇到以下问题：
问题1：克隆过程中子模块下载失败
典型报错：
fatal: clone of 'https://github.com/...' into submodule path failed解决方案分三步：
- 先克隆主仓库（不加
--recursive参数） - 进入项目目录手动初始化子模块：
git submodule update --init --recursive - 对仍然失败的子模块单独处理：
cd <子模块路径> git checkout <指定commit hash>
问题2：网络超时导致RPC失败
当出现类似错误时：
error: RPC failed; curl 56 GnuTLS recv error (-9)可以尝试以下配置组合：
git config --global http.postBuffer 524288000 git config --global http.maxRequestBuffer 100M git config --global core.compression 0如果还是不行，建议：
- 更换Git协议（https→git）
- 使用镜像源（如国内用户可用gitee镜像）
- 分时段多次尝试（避开网络高峰）
2. 编译环境配置与疑难解答
2.1 依赖安装的正确姿势
官方提供的ubuntu.sh脚本虽然方便，但有时会因为网络问题导致部分依赖安装失败。更可靠的方式是分步安装：
# 基础工具链 sudo apt-get install -y python3-pip python3-dev python3-wheel # Gazebo相关 sudo apt-get install -y gazebo11 libgazebo11-dev # 其他核心依赖 sudo apt-get install -y \ libeigen3-dev \ libopencv-dev \ protobuf-compiler \ geographiclib-tools常见编译错误排查表：
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
Could NOT find Eigen3 | Eigen3头文件路径错误 | sudo apt install libeigen3-dev |
OpenCV not found | OpenCV版本冲突 | 明确指定4.2版本：sudo apt install libopencv-dev=4.2.0+dfsg-5 |
protoc version mismatch | protobuf版本不一致 | 统一使用系统版本：sudo pip uninstall protobuf |
2.2 PX4编译的特殊参数
针对v1.12.3版本，推荐使用以下编译命令：
make px4_sitl_default gazebo如果遇到内存不足（特别是在虚拟机中），可以添加：
make px4_sitl_default gazebo -j $(($(nproc)/2))提示：首次编译建议保持终端打开，因为Gazebo首次启动会下载模型，可能需要交互确认
3. ROS与MAVROS集成配置
3.1 版本匹配原则
PX4 v1.12.3的最佳配套版本：
- ROS Noetic（Ubuntu 20.04默认）
- MAVROS 1.3.0+
安装命令：
sudo apt install ros-noetic-mavros ros-noetic-mavros-extras验证MAVROS安装：
roslaunch mavros px4.launch fcu_url:="udp://:14540@127.0.0.1:14557"正常应该看到类似输出：
[ INFO] [1620000000.000000]: MAVROS started. MY ID 1.240, TARGET ID 1.1]3.2 常见通信问题排查
当QGC地面站能连接但MAVROS无法通信时，检查以下方面：
端口冲突：
netstat -tulnp | grep 14540确保没有其他程序占用端口
消息类型不匹配： 在PX4启动参数中添加：
make px4_sitl_default gazebo PX4_SIM_MODEL=irisTF树配置： 检查~/.bashrc中是否有正确的环境变量：
source ~/PX4-Autopilot/Tools/setup_gazebo.bash ~/PX4-Autopilot/ ~/PX4-Autopilot/build/px4_sitl_default export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:~/PX4-Autopilot
4. 显示异常与系统级问题解决
4.1 屏幕旋转问题
当Gazebo启动后出现显示器旋转时，快速恢复命令：
xrandr --output eDP-1 --rotate normal如何确定显示器名称：
xrandr | grep connected输出示例：
eDP-1 connected primary 1920x1080+0+0 (normal left inverted right x axis y axis) 344mm x 194mm4.2 3D加速相关问题
在虚拟机中运行时可能出现Gazebo黑屏，解决方案：
- 检查虚拟机的3D加速是否启用
- 修改Gazebo启动参数：
export LIBGL_ALWAYS_SOFTWARE=1 - 或者使用轻量级渲染：
make px4_sitl_default gazebo_iris_opt_flow
4.3 系统资源优化
为提高仿真流畅度，建议：
限制Gazebo渲染质量： 编辑~/.gazebo/gui.ini：
[rendering] fps=30关闭不必要的系统服务：
sudo systemctl stop bluetooth.service sudo systemctl disable bluetooth.service调整交换空间（针对内存不足）：
sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile
5. 仿真环境验证与测试
5.1 基础功能测试流程
启动PX4仿真：
make px4_sitl_default gazebo另开终端启动MAVROS：
roslaunch mavros px4.launch fcu_url:="udp://:14540@127.0.0.1:14557"再开终端发送测试指令：
rostopic pub /mavros/setpoint_position/local geometry_msgs/PoseStamped \ "{header: {stamp: now, frame_id: 'map'}, pose: {position: {x: 0, y: 0, z: 2}}}" -r 20
5.2 常见测试问题速查表
| 现象 | 检查点 | 调试命令 |
|---|---|---|
| 无人机不起飞 | 是否解锁 | rostopic echo /mavros/state看armed状态 |
| 位置控制无效 | OFFBOARD模式是否激活 | rostopic echo /mavros/state看mode字段 |
| Gazebo模型抖动 | 实时性不足 | top查看CPU负载，考虑限制帧率 |
| MAVROS无响应 | 通信链路 | rostopic list检查话题是否存在 |
6. 进阶配置技巧
6.1 自定义仿真场景
在PX4-Autopilot目录下创建新世界文件：
mkdir -p ~/PX4-Autopilot/Tools/sitl_gazebo/worlds gedit ~/PX4-Autopilot/Tools/sitl_gazebo/worlds/custom.world然后通过参数指定：
make px4_sitl_default gazebo WORLD:=Tools/sitl_gazebo/worlds/custom.world6.2 多机仿真配置
修改启动命令添加实例号：
make px4_sitl_default gazebo PX4_SIM_MODEL=iris PX4_INSTANCE=1对应的MAVROS连接端口需要调整：
roslaunch mavros px4.launch fcu_url:="udp://:14540@127.0.0.1:14558"6.3 性能监控方案
实时查看系统资源占用：
watch -n 1 "echo 'CPU: '$(grep 'cpu ' /proc/stat | awk '{usage=($2+$4)*100/($2+$4+$5)} END {print usage}')'%'; echo 'Mem: '$(free -m | awk '/Mem/{print $3}')'MB'"Gazebo资源监控：
gz stats -p7. 环境备份与恢复策略
7.1 关键配置文件备份
建议定期备份以下目录：
# PX4配置 ~/.PX4/ # Gazebo模型 ~/.gazebo/ # ROS工作空间 ~/catkin_ws/src/可以创建自动化备份脚本：
#!/bin/bash BACKUP_DIR=~/px4_backup_$(date +%Y%m%d) mkdir -p $BACKUP_DIR cp -r ~/.PX4 $BACKUP_DIR cp -r ~/.gazebo $BACKUP_DIR cp -r ~/catkin_ws/src $BACKUP_DIR tar -czf $BACKUP_DIR.tar.gz $BACKUP_DIR7.2 快速环境恢复
从备份恢复的步骤：
- 解压备份文件
- 恢复关键配置：
cp -r backup/.PX4 ~/ cp -r backup/.gazebo ~/ - 重新编译工作空间：
cd ~/catkin_ws && catkin_make
8. 典型问题速查手册
8.1 Gazebo相关
问题：Gazebo启动后模型缺失
解决方案：
cd ~/.gazebo mkdir -p models cd models wget http://models.gazebosim.org/manifests/model-1_6.tar.gz tar -xzvf model-1_6.tar.gz8.2 PX4相关
问题：make编译时报错"undefined reference"
可能原因：编译缓存不一致
解决步骤：
make clean make distclean make px4_sitl_default gazebo8.3 ROS相关
问题：roslaunch报错"package not found"
检查并更新ROS环境：
source /opt/ros/noetic/setup.bash source ~/catkin_ws/devel/setup.bash如果仍然缺失，重新安装对应包：
sudo apt install ros-noetic-<package-name>
)
