Ubuntu22.04 + PX4 + ROS 2 + Gazebo Harmonic搭建四轴无人机仿真环境（ChatGPT 5.2 Pro）

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)

Ubuntu22.04 + PX4 + ROS 2 + Gazebo Harmonic搭建四轴无人机仿真环境（ChatGPT 5.2 Pro）

0. 安装前准备（强烈建议做）

1. 安装 ROS 2 Humble（Ubuntu 22.04 / deb 包方式）

1.1 设置 UTF-8 Locale

1.2 启用 Universe 源 + 安装 ROS2 apt 源配置包

1.3 安装 ROS2（Desktop）+ 开发工具

1.4 环境变量（每个终端自动 source）

1.5 初始化 rosdep（后续编译工作区基本必用）

1.6 验证 ROS2 是否正常

2. 安装 Gazebo Sim（推荐 Harmonic / LTS）

3. 安装 ROS2 ↔ Gazebo 的集成包（ros_gz）

3.1 关键选择：Humble 官方默认配对是 Fortress，我们装 Harmonic

3.2 在 "Gazebo Harmonic + ROS2 Humble" 下的安装方式

3.3 用 ROS2 启动 Gazebo（快速验证联动）

4. 安装 PX4（SITL）+ Gazebo 四轴模型（推荐 gz_x500）

4.1 获取 PX4 源码并安装开发工具链

4.2 启动四轴 Gazebo 仿真（gz_x500）

5. ROS2 ↔ PX4 通信（uXRCE-DDS）：安装并运行 Micro XRCE-DDS Agent

5.1 安装/编译 Micro-XRCE-DDS-Agent（按 PX4 官方给定版本）

5.2 运行 Agent（UDP 8888）

5.3 启动 PX4 仿真（另一个终端）

6. 建 ROS2 工作区（px4_msgs + px4_ros_com）并验证能收到 PX4 话题

6.1 额外 Python 依赖（PX4 文档要求）

6.2 创建工作区 + clone 两个仓库 + colcon build

6.3 运行 listener（第三个终端）

7. 最终推荐的"3 终端"启动顺序（最稳）

8. 最常见踩坑点（按出现概率排序）

8.1 ROS2 安装过程中系统包被动到（systemd/udev）

8.2 Gazebo Classic（gazebo11）与 gz-harmonic 冲突

8.3 Humble 默认是 Fortress，但你要用 Harmonic

8.4 gz_x500 target 不存在

4. 安装 PX4（SITL）+ Gazebo 四轴模型（推荐 `gz_x500`）

4.2 启动四轴 Gazebo 仿真（`gz_x500`）

8.4 `gz_x500` target 不存在