Ubuntu 22.04 上搭建「四轴无人机（四旋翼）虚拟仿真环境」的完整不踩坑流程。整体采用：
-
ROS 2：Humble（Ubuntu 22.04 官方主力 LTS）
-
Gazebo：Gazebo Sim – Harmonic（LTS）
-
无人机飞控/动力学：PX4 SITL + Gazebo（gz_x500 四轴模型）
-
ROS2 ↔ PX4 通信：uXRCE-DDS（Micro XRCE-DDS Agent + PX4 内置 client）
说明：如果你只装 ROS2+Gazebo 并不接 PX4，也可以跑 Gazebo/ROS 的 demo；但要做“能起飞、悬停、姿态/位置控制、传感器仿真”的四轴无人机环境，最常见/最完整的一条路就是 PX4 SITL + Gazebo + ROS2。PX4 官方也明确推荐 Ubuntu 22.04 + ROS2 Humble，并给出 uXRCE-DDS 的整套流程。(PX4 Docs)
0. 安装前准备（强烈建议做）
更新系统（ROS2 官方特别强调：22.04 上先 upgrade，避免 systemd/udev 相关问题）：
sudo apt update
sudo apt upgrade -y
sudo reboot
ROS2 安装文档明确提示了这个 upgrade 的必要性（尤其是 Ubuntu 22.04 的 systemd/udev 相关风险）。(ROS Documentation)
基础依赖（通用开发工具）：
sudo apt update
sudo apt install -y git curl wget gnupg lsb-release build-essential cmake python3-pip
1. 安装 ROS 2 Humble（Ubuntu 22.04 / deb 包方式）
按 ROS2 Humble 官方安装步骤（新版推荐用 ros2-apt-source 自动管理 key 与源）：
1.1 设置 UTF-8 Locale
locale # 看看当前是否 UTF-8
sudo apt update && sudo apt install -y locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8
locale # 再确认一遍
(ROS Documentation)
1.2 启用 Universe 源 + 安装 ROS2 apt 源配置包
sudo apt install -y software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install -y curl
export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F\\" '{print $4}')
curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
sudo dpkg -i /tmp/ros2-apt-source.deb
(ROS Documentation)
1.3 安装 ROS2（Desktop）+ 开发工具
sudo apt update
sudo apt upgrade -y # 再强调一次：22.04 很建议升级后再装
sudo apt install -y ros-humble-desktop
sudo apt install -y ros-dev-tools
(ROS Documentation)
1.4 环境变量（每个终端自动 source）
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc
ROS2 官方也说明需要 source /opt/ros/humble/setup.bash。(ROS Documentation)
1.5 初始化 rosdep（后续编译工作区基本必用）
sudo apt install -y python3-rosdep
sudo rosdep init
rosdep update
(ROS Documentation)
1.6 验证 ROS2 是否正常
开两个终端分别执行：
终端 A：
source /opt/ros/humble/setup.bash
ros2 run demo_nodes_cpp talker
终端 B：
source /opt/ros/humble/setup.bash
ros2 run demo_nodes_py listener
(ROS Documentation)
2. 安装 Gazebo Sim（推荐 Harmonic / LTS）
Gazebo 现在分两条线：
-
Gazebo Classic（gazebo11）：老版本（不建议新项目再上）
-
Gazebo Sim（gz sim）：新 Gazebo（建议用它做 ROS2/PX4 新仿真）
Gazebo Harmonic 的 Ubuntu 22.04 二进制安装（官方文档）如下：
sudo apt-get update
sudo apt-get install -y curl lsb-release gnupg
sudo curl https://packages.osrfoundation.org/gazebo.gpg –output /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg
echo "deb [arch=$(dpkg –print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] https://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null
sudo apt-get update
sudo apt-get install -y gz-harmonic
(Gazebo)
注意：官方明确提示 gz-harmonic 默认不能和 gazebo11（Gazebo Classic）共存（因为命令行工具 gz 会冲突）。如果你之前装过 gazebo11，建议先卸载 classic 再装 Harmonic。(Gazebo)
简单验证：
gz sim –version
3. 安装 ROS2 ↔ Gazebo 的集成包（ros_gz）
“ROS2 + Gazebo 实现”意味着能用 ROS2 launch/桥接控制 Gazebo、收发传感器话题等，这就需要 ros_gz。
3.1 关键选择：Humble 官方默认配对是 Fortress，我们装 Harmonic
Gazebo 官方说明：
-
ROS2 Humble 官方完整支持/测试的 Gazebo 版本是 Fortress
-
Harmonic + Humble 可以用，但要装 非官方配对的包，并且会和 ros-humble-ros-gz*（Fortress 配套包）产生冲突 (Gazebo)
3.2 在 “Gazebo Harmonic + ROS2 Humble” 下的安装方式
已经装了 gz-harmonic，那就按 Gazebo 官方文档安装对应的 ROS 集成包：
sudo apt-get update
sudo apt-get install -y ros-humble-ros-gzharmonic
(Gazebo)
重要提醒：ros-humble-ros-gzharmonic 这套 会和 ros-humble-ros-gz*（Humble 官方 Fortress 配套）冲突，不要两套混装。(Gazebo)
3.3 用 ROS2 启动 Gazebo（快速验证联动）
source /opt/ros/humble/setup.bash
ros2 launch ros_gz_sim gz_sim.launch.py gz_args:="shapes.sdf"
这条命令来自 ros_gz_sim_demos/ros_gz_sim 的示例说明：用 ROS2 launch 拉起 Gazebo 并加载 shapes.sdf。(ROS Index)
4. 安装 PX4（SITL）+ Gazebo 四轴模型（推荐 gz_x500）
这是你要“像无人机一样能飞”的关键部分：PX4 给你飞控、混控、传感器接口、Offboard 等。
4.1 获取 PX4 源码并安装开发工具链
cd ~
git clone https://github.com/PX4/PX4-Autopilot.git –recursive
然后运行官方安装脚本：
-
我们已经手动装好了 Gazebo（比如上面装了 gz-harmonic），并且不想 PX4 脚本动你的仿真器：
bash ./PX4-Autopilot/Tools/setup/ubuntu.sh –no-sim-tools
- 如果你想让 PX4 脚本自动装它推荐的仿真器/工具（省事）：
bash ./PX4-Autopilot/Tools/setup/ubuntu.sh
PX4 ROS2 指南明确给出上述 clone + ubuntu.sh，并说明 –no-sim-tools 用于保留你现有的 simulator 安装。(PX4 Docs)
然后编译一次 SITL：
cd ~/PX4-Autopilot
make px4_sitl
(PX4 Docs)
4.2 启动四轴 Gazebo 仿真（gz_x500）
cd ~/PX4-Autopilot
make px4_sitl gz_x500
PX4 仿真文档给出的 Gazebo（新 Gazebo / gz）启动示例就是 make px4_sitl gz_x500。(PX4 Docs)
常见报错处理： 如果你遇到 ninja: error: unknown target 'gz_x500'，PX4 文档建议：
make distclean
make px4_sitl gz_x500
(PX4 Docs)
5. ROS2 ↔ PX4 通信（uXRCE-DDS）：安装并运行 Micro XRCE-DDS Agent
PX4 v1.14 起，ROS2 与 PX4 的深度集成通信走 uXRCE-DDS：PC 上跑 Agent，PX4（SITL）里跑 client（仿真构建通常会自动启动并连 UDP 8888）。(PX4 Docs)
5.1 安装/编译 Micro-XRCE-DDS-Agent（按 PX4 官方给定版本）
cd ~
git clone -b v2.4.3 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 /usr/local/lib/
(PX4 Docs)
5.2 运行 Agent（UDP 8888）
开一个终端：
MicroXRCEAgent udp4 -p 8888
(PX4 Docs)
5.3 启动 PX4 仿真（另一个终端）
cd ~/PX4-Autopilot
make px4_sitl gz_x500
PX4 文档说明：SITL 会自动连接本机 UDP 8888 的 uXRCE-DDS agent，并在控制台输出创建 data writer 的 INFO。(PX4 Docs)
6. 建 ROS2 工作区（px4_msgs + px4_ros_com）并验证能收到 PX4 话题
PX4 官方 ROS2 指南给了一个 “sensor_combined_listener” 的最小闭环验证：能收到 PX4 发布的传感器数据就说明链路通了。(PX4 Docs)
6.1 额外 Python 依赖（PX4 文档要求）
pip install –user -U empy==3.3.4 pyros-genmsg setuptools
(PX4 Docs)
6.2 创建工作区 + clone 两个仓库 + colcon build
mkdir -p ~/ws_sensor_combined/src/
cd ~/ws_sensor_combined/src/
git clone https://github.com/PX4/px4_msgs.git
git clone https://github.com/PX4/px4_ros_com.git
cd ..
source /opt/ros/humble/setup.bash
colcon build
(PX4 Docs)
提醒：px4_msgs 的分支需要尽量和你正在运行的 PX4 固件消息定义匹配；如果消息版本不兼容，PX4 文档还提到需要启动 message translation node。(PX4 Docs)
6.3 运行 listener（第三个终端）
cd ~/ws_sensor_combined/
source /opt/ros/humble/setup.bash
source install/local_setup.bash
ros2 launch px4_ros_com sensor_combined_listener.launch.py
正常的话，你会看到持续打印的传感器数据（PX4 文档给出了示例输出）。(PX4 Docs)
7. 最终推荐的“3 终端”启动顺序（最稳）
终端 1：Agent
MicroXRCEAgent udp4 -p 8888
(PX4 Docs)
终端 2：PX4 + Gazebo 四轴
cd ~/PX4-Autopilot
make px4_sitl gz_x500
(PX4 Docs)
终端 3：ROS2 监听/控制节点
cd ~/ws_sensor_combined/
source /opt/ros/humble/setup.bash
source install/local_setup.bash
ros2 launch px4_ros_com sensor_combined_listener.launch.py
(PX4 Docs)
8. 最常见踩坑点（按出现概率排序）
8.1 ROS2 安装过程中系统包被动到（systemd/udev）
按 ROS2 文档建议：装 ROS2 前务必 sudo apt upgrade（尤其是全新 22.04 系统）。(ROS Documentation)
8.2 Gazebo Classic（gazebo11）与 gz-harmonic 冲突
Gazebo Harmonic 文档明确：gz-harmonic 默认不能和 gazebo11 共存。(Gazebo)
8.3 Humble 默认是 Fortress，但你要用 Harmonic
Gazebo 官方写得很清楚：Humble 官方支持 Fortress；Harmonic + Humble 需要用 ros-humble-ros-gzharmonic，并且会与 ros-humble-ros-gz* 冲突。(Gazebo)
8.4 gz_x500 target 不存在
按 PX4 文档：make distclean 后重来。(PX4 Docs)
