前言

最近开始学习具身智能，需要在 Ubuntu 24.04 上搭建一个完整的机器人仿真环境，用于后续的视觉抓取项目。我选择 ROS2 Jazzy + Gazebo Harmonic + UR5e 机械臂作为基础平台。然而，在运行 MoveIt 进行运动规划时，遇到了 Rviz 窗口反复闪烁、最后崩溃的问题。

本文将详细记录从操作系统环境准备到最终成功运行的全过程，以及问题排查的思路和解决方法。希望帮助遇到类似问题的朋友少走弯路。

---

一、环境说明

• 操作系统：Ubuntu 24.04 LTS (Noble)

• ROS2 版本：Jazzy (因为 Ubuntu 24.04 官方推荐)

• Gazebo 版本：Harmonic

• 机器人模型：Universal Robots UR5e

• 硬件：普通 PC，NVIDIA 显卡（可选）

---

二、环境搭建步骤

2.1 安装 ROS2 Jazzy

我使用了鱼香ROS的一键安装脚本，非常方便：

wget http://fishros.com/install -O fishros && chmod +x fishros && ./fishros

按提示选择：

• 1. 一键安装 ROS2

• 1. 更换系统源（推荐，加快下载）

• 1. [jazzy] (ROS2)

• 1. 桌面版（包含 RViz2 等工具）

安装完成后，将 ROS2 环境变量加入 ~/.bashrc：

echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc
source ~/.bashrc

2.2 安装 Gazebo Harmonic 及桥接包

Gazebo Harmonic 是 Ubuntu 24.04 下的默认版本，与 ROS2 Jazzy 完美兼容。

# 添加 Gazebo 官方源
sudo apt update
sudo apt install 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] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null
sudo apt update

安装 Gazebo Harmonic 本体：

sudo apt install gz-harmonic -y

安装 ROS2 与 Gazebo 的桥接包 ros_gz_bridge：

sudo apt install ros-jazzy-ros-gz -y

验证 Gazebo 是否正常：

gz sim shapes.sdf

如果看到一个带有几何体的 3D 窗口，说明 Gazebo 安装成功。

2.3 安装 UR 机器人相关包

为了仿真 UR5e 机械臂，需要安装以下三个包：

sudo apt install ros-jazzy-ur-simulation-gz    # Gazebo 仿真模型
sudo apt install ros-jazzy-ur-moveit-config    # MoveIt 配置
sudo apt install ros-jazzy-ur-description      # URDF 描述文件

这些包提供了 UR5e 的模型、控制器配置以及 MoveIt 规划所需的文件。

---

三、启动 UR5e 仿真（报错）

按照官方教程，使用以下命令启动 UR5e 仿真：

ros2 launch ur_simulation_gz ur_sim_moveit.launch.py ur_type:=ur5e

预期结果：Gazebo 窗口出现 UR5e 模型，Rviz 窗口也打开，并且可以通过 Rviz 的交互面板拖动末端执行器来规划运动。

但现实却很残酷：

• Gazebo 窗口正常加载模型。

• Rviz 窗口打开后，机械臂模型不断闪烁、重绘，几乎无法操作。

• 大约 5-10 秒后，Rviz 进程自动崩溃退出。

终端最后几行日志显示：

[rviz2-9] [INFO] ... Loaded robot model in 0.02 seconds
...
[rviz2-9] Error:   Semantic description is not specified for the same robot as the URDF
          at line 681 in ./src/model.cpp

---

四、问题排查过程

4.1 从报错信息入手：Semantic description

报错 Semantic description is not specified for the same robot as the URDF 明确指出 MoveIt 无法加载机器人的语义描述文件（SRDF）。SRDF 文件是 MoveIt 用来定义关节组、末端执行器、虚拟关节等语义信息的。

检查系统中是否存在 UR5e 的 SRDF 文件：

find /opt/ros/jazzy -name "*.srdf"

没有输出。说明系统中没有现成的 .srdf 文件。

原来只有 .xacro 模板文件，没有生成好的 .srdf。这意味着我们需要手动从 xacro 转换成 SRDF。

4.2 环境变量

执行 which xacro 没有任何输出。而 ROS2 的很多工具都安装在 /opt/ros/jazzy/bin/ 下，这个路径只有在 source /opt/ros/jazzy/setup.bash 后才会加入 PATH。

于是执行：

source /opt/ros/jazzy/setup.bash
which xacro
# 输出：/opt/ros/jazzy/bin/xacro

原来如此！ 我虽然已经在 ~/.bashrc 中添加了 source 命令，但是那是之后才加的。而在第一次启动仿真时，新终端并没有自动加载 ROS2 环境（因为当时我还没有把 source 命令加到 ~/.bashrc）。后来加了，但生成 SRDF 的终端可能没有重新加载，或者使用了 sudo 导致环境变量丢失。

因此，xacro 命令不可用 → 无法生成 SRDF → MoveIt 启动时找不到语义描述 → Rviz 崩溃。

---

五、解决方案

5.1 验证 xacro 可用

which xacro   # 必须显示 /opt/ros/jazzy/bin/xacro

5.2 生成 UR5e 的 SRDF 文件

注意：使用 sudo 时，root 环境可能没有继承 PATH，因此需要将当前 PATH 传递过去。

cd /opt/ros/jazzy/share/ur_moveit_config/srdf
sudo env "PATH=$PATH" xacro ur.srdf.xacro robot_type:=ur5e > ur5e.srdf

5.3 重新启动仿真

ros2 launch ur_simulation_gz ur_sim_moveit.launch.py ur_type:=ur5e

这次，Rviz 窗口稳定显示 UR5e 模型，没有闪烁。你可以拖动 Rviz 中的红色/绿色/蓝色小球，然后点击 Plan & Execute，机械臂就会在 Gazebo 中按照规划路径运动。

---

六、最终效果

• Gazebo 中 UR5e 模型正常。

• Rviz 中机械臂模型稳定，交互流畅。

• MoveIt 运动规划成功执行。

• 环境可用于后续集成 GraspNet 视觉抓取项目。

---

七、经验总结与避坑指南

现象	直接原因	根本原因	解决方法
Rviz 崩溃，报错 Semantic description missing	MoveIt 找不到 ur5e.srdf	xacro 命令不可用 → 无法从 .xacro 生成 .srdf	1. 确保 ROS2 环境变量已 source 2. 生成 SRDF 文件 3. 重启仿真

1. 环境变量。几乎所有 ROS2 命令行工具（ros2, rviz2, xacro, gz 等）都依赖于 source /opt/ros/jazzy/setup.bash。务必将其写入 ~/.bashrc，并确认每次新终端都自动加载。

2. 使用 sudo 时环境变量会丢失。如果需要在 sudo 下运行 ROS2 命令，请使用 sudo env "PATH=$PATH" <command> 或先 sudo -s 再 source。

3. 不同 Ubuntu 版本下软件包行为可能不同。Ubuntu 22.04 的 ur_moveit_config 可能直接包含 .srdf，而 24.04 只提供了 .xacro。遇到问题要多检查包内文件