ROS 2 + Gazebo + MoveIt 2 开发环境安装指南

(Ubuntu 24.04 + WSL2 + ROS 2 Jazzy)

适用环境：Windows 10/11 (WSL2) + Ubuntu 24.04 LTS
核心版本：ROS 2 Jazzy Jalisco + Gazebo Harmonic + MoveIt 2
更新时间：2026-03-25

---

📋 目录

1. 前置准备
2. 安装 ROS 2 Jazzy
3. 安装 Gazebo Harmonic
4. 安装 MoveIt 2
5. 验证安装
6. 常见问题

---

1. 前置准备

1.1 更新 WSL2 (Windows 端)

在 PowerShell (管理员模式) 中执行：

wsl --update
wsl --set-default-version 2
wsl --list --verbose  # 确认 Ubuntu 版本为 2

1.2 进入 Ubuntu 24.04 终端

wsl -d Ubuntu

1.3 系统基础配置

# 更新软件源
sudo apt update && sudo apt upgrade -y

# 安装必要工具
sudo apt install -y curl gnupg lsb-release locales software-properties-common

# 设置 UTF-8 编码 (ROS 2 必需)
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

# 验证图形支持 (WSLg)
sudo apt install -y mesa-utils
glxinfo | grep "OpenGL version"

✅ 如果输出了 OpenGL 版本信息，说明 WSLg 图形加速已就绪。

---

2. 安装 ROS 2 Jazzy

2.1 添加 ROS 2 软件源

# 添加 ROS 2 GPG 密钥
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

# 添加 ROS 2 软件源 (Ubuntu 24.04 = noble)
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

# 【国内用户可选】使用清华源加速
# echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

2.2 安装 ROS 2 Jazzy 桌面完整版

sudo apt update
sudo apt install -y ros-jazzy-desktop

2.3 安装开发工具

sudo apt install -y ros-dev-tools python3-colcon-common-extensions python3-rosdep python3-flake8-docstrings python3-pip python3-pytest-cov

2.4 配置环境变量

# 添加到 ~/.bashrc
echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc
echo "export ROS_DOMAIN_ID=0" >> ~/.bashrc  # 可选：设置域 ID
source ~/.bashrc

# 验证 ROS 2 环境
ros2 --version

---

3. 安装 Gazebo Harmonic

⚠️ 重要：Gazebo Harmonic 不在默认软件源中，需单独添加 OSRF 源。

3.1 添加 Gazebo 官方软件源

# 添加 Gazebo GPG 密钥
sudo curl https://packages.osrfoundation.org/gazebo.gpg --output /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg

# 添加 Gazebo 软件源 (Ubuntu 24.04 = noble)
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

# 【国内用户可选】如果 OSRF 源访问慢，可尝试手动下载 .deb 包安装

# 更新软件源
sudo apt update

3.2 安装 Gazebo Harmonic

# 安装 Gazebo Harmonic 完整包
sudo apt install -y gz-harmonic

# 如果上述命令失败，尝试安装核心组件
# sudo apt install -y gz-sim-harmonic gz-common-harmonic gz-physics-harmonic gz-rendering-harmonic gz-gui-harmonic

3.3 安装 ROS 2 + Gazebo 桥梁ros_gz包

这一步是为了让ros2和gz进行通信

# 查看相关的 ros_gz 包 
sudo apt search ros-jazzy-ros-gz
# 直接安装所有相关包(我不是很确定到底哪个是 ROS 2 与 Gazebo 通信用的)
sudo apt install -y ros-jazzy-ros-gz*

3.4 验证 Gazebo

# 检查版本
gz sim --version

# 启动 Gazebo (应弹出图形窗口)
gz sim

🎯 注意：从 Gazebo Harmonic 开始，命令从 gazebo 改为 gz sim。

---

4. 安装 MoveIt 2

4.1 安装 MoveIt 2 核心包

# 安装 MoveIt 2 (包含 RViz2 插件、运动规划器等)
sudo apt install -y ros-jazzy-moveit

# 安装可视化工具
sudo apt install -y ros-jazzy-moveit-visual-tools

# 安装示例资源包 (可选)
sudo apt install -y ros-jazzy-moveit-resources-panda-description

4.2 验证 MoveIt 2

# 启动 MoveIt 设置助手 (应弹出图形界面)
ros2 launch moveit_setup_assistant setup_assistant.launch.py

---

5. 验证安装

5.1 综合测试脚本

创建测试文件 ~/test_ros2_gazebo_moveit.sh：

#!/bin/bash

echo "=== ROS 2 版本检查 ==="
ros2 --version

echo -e "\n=== Gazebo 版本检查 ==="
gz sim --version

echo -e "\n=== MoveIt 2 检查 ==="
ros2 pkg list | grep moveit

echo -e "\n=== 测试 ROS 2 节点通信 ==="
# 终端 1: 启动 talker (后台运行)
ros2 run demo_nodes_cpp talker &
TALKER_PID=$!

# 等待 2 秒
sleep 2

# 终端 2: 启动 listener (运行 5 秒后退出)
timeout 5 ros2 run demo_nodes_cpp listener

# 清理 talker 进程
kill $TALKER_PID 2>/dev/null

echo -e "\n=== 测试 Gazebo 启动 ==="
echo "尝试启动 Gazebo... (请在 5 秒内观察是否弹出窗口)"
timeout 5 gz sim &

echo -e "\n=== 测试 MoveIt 设置助手 ==="
echo "尝试启动 MoveIt Setup Assistant... (请观察是否弹出窗口)"
timeout 5 ros2 launch moveit_setup_assistant setup_assistant.launch.py &

echo -e "\n✅ 所有基础检查完成！"

赋予执行权限并运行：

chmod +x ~/test_ros2_gazebo_moveit.sh
~/test_ros2_gazebo_moveit.sh

5.2 预期输出

• ✅ ros2 --version 显示 ros2 0.32.x (jazzy)
• ✅ gz sim --version 显示 Gazebo Sim Harmonic X.X.X
• ✅ ros2 pkg list | grep moveit 列出多个 moveit 相关包
• ✅ Talker/Listener 正常收发消息
• ✅ Gazebo 和 MoveIt Setup Assistant 成功弹出图形窗口

---

6. 常见问题

6.1 Gazebo 无法找到包 (Unable to locate package gz-harmonic)

解决方案：

# 1. 确认 Gazebo 源已正确添加
cat /etc/apt/sources.list.d/gazebo-stable.list

# 2. 如果不是 noble，手动修正
echo "deb [arch=amd64] http://packages.osrfoundation.org/gazebo/ubuntu-stable noble main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list

# 3. 重新更新并安装
sudo apt update
sudo apt install -y gz-harmonic

6.2 Gazebo/MoveIt 窗口无法打开或黑屏

可能原因：WSLg 未正常工作或显卡驱动问题。

解决方案：

# 1. 确保 Windows 宿主机显卡驱动最新

# 2. 在 WSL 中安装 Mesa 驱动
sudo apt install -y libgl1-mesa-glx libegl1-mesa libglx-mesa0

# 3. 尝试设置环境变量
export LIBGL_ALWAYS_INDIRECT=0

# 4. 重启 WSL (在 PowerShell 中)
# wsl --shutdown
# 然后重新进入 Ubuntu

6.3 中文路径问题

切记：ROS 2 工作空间路径不能包含中文或空格。

❌ 错误示例：/home/user/我的机器人/ws
✅ 正确示例：/home/user/my_robot_ws

6.4 网络下载速度慢 (国内用户)

一般来说用来wsl基本上没有链接上的问题
解决方案：替换为国内镜像源。

# ROS 2 源 (清华)
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

# Gazebo 源 (目前无官方国内镜像，可尝试代理或手动下载 .deb)

6.5 WSL2 性能优化

在 Windows 用户目录下 (%USERPROFILE%) 创建或编辑 .wslconfig 文件：

[wsl2]
memory=8GB              # 限制最大内存
processors=4            # 限制 CPU 核心数
swap=4GB                # 交换空间
localhostForwarding=true
guiApplications=true    # 确保 GUI 应用支持

然后重启 WSL：

wsl --shutdown

---

🎉 安装完成！

现在你已经成功搭建了 ROS 2 Jazzy + Gazebo Harmonic + MoveIt 2 的完整开发环境。接下来可以：

1. 创建工作空间：mkdir -p ~/ros2_ws/src
2. 克隆机器人仿真包 (如 Panda机械臂、UR机械臂等)
3. 使用 MoveIt Setup Assistant 配置自己的机器人
4. 开始编写运动规划代码！

---

📚 参考资源

• ROS 2 Jazzy 官方文档
• Gazebo Harmonic 文档
• MoveIt 2 教程
• 鱼香ROS 一键安装脚本

---

祝你开发顺利！🤖