WSL2 + ROS2 Jazzy + Gazebo Harmonic 环境搭建：我踩过的6个坑（2026最新版）

做具身智能VLM项目的第一步，就是把环境搭起来。本以为照着教程一步步来就行，结果踩了好几个坑——WSL版本不对、Gazebo包名变了、内存不够用……折腾了一天终于跑通了。把我遇到的问题和解决方案整理出来，希望能帮到后来的人。

---

前言：为什么选这套环境？

我在做一个基于Qwen2.5-VL-3B的仿真机器人视觉感知项目，简单说就是让VLM模型"看懂"Gazebo仿真环境里的画面，然后控制机器人做事情。

技术栈选型：

• WSL2 + Ubuntu 24.04：Windows下做Linux开发最方便的方案
• ROS2 Jazzy：最新LTS版本，原生支持Ubuntu 24.04
• Gazebo Harmonic：新版Gazebo Sim（注意不是Classic！），和ROS2 Jazzy配套
• Qwen2.5-VL-3B：后续要部署的视觉语言模型
• RTX 5060 8GB：我的显卡，刚好能跑3B模型

网上找了几篇教程，发现要么是旧版ROS2（Humble/Iron），要么Gazebo还是Classic版本，要么WSL配置说得不清楚。我跟着做的过程中踩了不少坑，这里全部记录下来。

---

一、环境准备

1.1 安装WSL2 Ubuntu 24.04

第一步：以管理员身份打开PowerShell

这是第一个容易懵的地方——怎么以管理员身份打开？最简单的方法：

• 按 Win + X 键，弹出快速菜单
• 选择 “终端(管理员)” 或 “Windows PowerShell(管理员)”
• 弹出UAC提示，点"是"就行了

不用纠结在哪个目录下打开，WSL安装是系统级的，跟当前目录没关系。

第二步：安装WSL和Ubuntu

正常来说，执行这个命令就够了：

wsl --install -d Ubuntu-24.04

但是！我第一次执行就报错了：

（报错：无效的分发名称 ‘Ubuntu-24.04’）

🚫 坑1：WSL版本太旧，不支持 Ubuntu-24.04

问题描述：
执行 wsl --install -d Ubuntu-24.04 报错：

无效的分发名称："Ubuntu-24.04"。
有关有效分发名称的列表，请使用 "wsl --online"。
错误代码: 0x80070057

原因：
系统自带的WSL版本比较旧，还不认识 Ubuntu-24.04 这个名字。旧版WSL的应用商店列表里最高可能只有Ubuntu 22.04。

解决办法：手动更新WSL内核

1. 下载WSL更新包：

   • 官方下载地址：https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi

2. 双击下载的 wsl_update_x64.msi，按提示安装

3. 重启电脑（这步很重要，不重启可能不生效）

4. 如果还提示"未启用WSL功能"，在管理员PowerShell中执行：

   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
   

5. 重启后再执行：

   wsl --install -d Ubuntu-24.04
   

6. 安装完成后设置用户名和密码，就进入Ubuntu了。

---

二、基础系统配置

2.1 换源+更新系统

进入Ubuntu后，先更新一下：

sudo apt update && sudo apt upgrade -y

2.2 安装基础依赖

sudo apt install -y curl gnupg2 lsb-release software-properties-common

🚫 坑2：WSL吃内存太猛，Windows卡得动不了

问题描述：
WSL默认会吃掉你大部分内存，我16GB内存的电脑，开了WSL后Windows这边只剩2-3GB，浏览器都卡。

解决办法：配置 .wslconfig 限制WSL资源

第一步：创建配置文件

在Windows中按 Win + R，输入 notepad 回车，打开记事本。

粘贴以下内容：

[wsl2]
memory=12GB
processors=8
swap=4GB
localhostForwarding=true

⚠️ 注意：memory 和 processors 要根据你电脑的实际配置调整：

• 内存16GB → 设 memory=12GB（给Windows留4GB）
• 内存8GB → 设 memory=6GB
• 处理器核心数设为你电脑逻辑处理器数量的一半左右

怎么看自己电脑配置？

• 按 Ctrl + Shift + Esc 打开任务管理器
• 点"性能"标签页
• 点"内存"：看右上角总内存
• 点"CPU"：看右下角逻辑处理器数量

第二步：保存配置文件

• 点"文件" → “另存为”
• 文件名：.wslconfig（注意前面有个点！）
• 保存位置：C:\Users\你的Windows用户名\（就是你的用户文件夹）
• 保存类型：选择"所有文件 (.)"
• 点保存

第三步：重启WSL使配置生效

在管理员PowerShell中执行：

wsl --shutdown

然后重新打开Ubuntu终端就行。

---

三、安装ROS2 Jazzy

3.1 添加ROS2软件源

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

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

# 更新软件源
sudo apt update

3.2 安装ROS2 Jazzy桌面完整版

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

3.3 安装开发工具

sudo apt install -y python3-colcon-common-extensions python3-rosdep python3-vcstool

# 初始化rosdep
sudo rosdep init
rosdep update

🚫 坑3：每次打开终端都要重新source环境变量

问题描述：
新开一个终端，输入 ros2 --version 就提示找不到命令，必须每次手动 source /opt/ros/jazzy/setup.bash 才行。

解决办法：把环境变量写入 .bashrc

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

这样以后每次打开终端都会自动加载ROS2环境了。

---

四、安装Gazebo Harmonic（重点坑区）

这部分是我踩坑最多的地方。网上很多教程还是旧版的 gazebo_ros 那一套，但在 ROS2 Jazzy + Gazebo Harmonic 这套组合里，集成方式已经完全变了。

4.1 先讲清楚：新旧架构的区别

旧版（ROS2 Humble + Gazebo Classic）	新版（ROS2 Jazzy + Gazebo Harmonic）
包名：gazebo-ros-pkgs	包名：ros-jazzy-ros-gz
启动命令：ros2 launch gazebo_ros ...	启动命令：ros2 launch ros_gz_sim ...
命令：gazebo	命令：gz sim

很多教程写的 sudo apt install ros-jazzy-gazebo-ros-pkgs 是旧版的，在Jazzy里根本不对！

4.2 正确的安装方式

第一步：添加Gazebo官方源

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

# 添加Gazebo软件源
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本体

sudo apt install gz-harmonic -y

第三步：安装ROS2-Gazebo桥接包

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

🚫 坑4：sudo apt install gz-harmonic 报错找不到包

问题描述：

E: Unable to locate package gz-harmonic

原因：系统软件源里没有Gazebo的官方源，apt找不到这个包。

解决办法：手动添加Gazebo官方源（就是上面第一步的操作），然后 sudo apt update 再安装。

🚫 坑5：装了ros-gz后，gz sim 命令还是找不到

问题描述：
安装了 ros-jazzy-ros-gz 后，执行 gz sim --help 还是提示 gz: command not found。

原因：ros-jazzy-ros-gz 主要提供的是桥接功能（让ROS2和Gazebo通信），但不一定包含Gazebo仿真器本体。

解决办法：单独安装Gazebo本体：

# 先确保添加了Gazebo官方源（见坑4的解决办法）
sudo apt install gz-harmonic -y

装完之后 gz sim --help 就能用了。

🚫 坑6：ros2 launch gazebo_ros empty_world.launch.py 报错

问题描述：
照着旧教程执行启动命令，报错：

Package 'gazebo_ros' not found

原因：ROS2 Jazzy用的是全新的 ros_gz 桥接包体系，gazebo_ros 是旧版Gazebo Classic的包名，在Jazzy里已经不存在了。

解决办法：使用新架构的正确命令：

# 旧版命令（Jazzy里不能用）：
# ros2 launch gazebo_ros empty_world.launch.py

# 新版命令（Jazzy正确用法）：
ros2 launch ros_gz_sim gz_sim.launch.py

💡 核心结论：在ROS2 Jazzy环境下，请把所有与Gazebo相关的命令和包名，从旧的 gazebo_ros 迁移到新的 ros_gz_sim 体系。

---

五、完整安装验证清单

环境搭好了，怎么确认真的没问题？给你一个完整的检查清单，依次执行：

✅ 检查1：ROS2命令行工具

ros2 --help

显示帮助信息 → ✅ 通过

✅ 检查2：ROS2发行版

echo $ROS_DISTRO

输出 jazzy → ✅ 通过

✅ 检查3：Gazebo命令

gz sim --help

显示帮助信息 → ✅ 通过

✅ 检查4：ROS2与Gazebo桥接包

ros2 pkg list | grep ros_gz

能看到 ros_gz_bridge、ros_gz_image、ros_gz_sim 等包 → ✅ 通过

✅ 检查5：ROS2话题通信（可选）

终端1运行：

ros2 run demo_nodes_cpp talker

终端2运行：

ros2 run demo_nodes_py listener

能看到消息在传输 → ✅ 通过

✅ 检查6：Gazebo与ROS2桥接（关键测试）

终端1启动Gazebo空世界（会打开一个GUI窗口）：

gz sim -r empty.sdf

终端2列出ROS2话题：

ros2 topic list

能看到 /clock、/world/empty/state 等话题 → ✅ 通过

---

六、创建工作空间

验证通过后，创建一个ROS2工作空间，为后续开发做准备：

# 创建工作空间目录
mkdir -p ~/vlm_robot_ws/src
cd ~/vlm_robot_ws

# 编译一下（空工作空间也能编译）
colcon build

# 把工作空间的环境变量也加到.bashrc
echo "source ~/vlm_robot_ws/install/setup.bash" >> ~/.bashrc
source ~/.bashrc

---

总结

这篇文章记录了我搭建 WSL2 + ROS2 Jazzy + Gazebo Harmonic 环境时遇到的6个坑：

1. WSL版本太旧 → 手动下载WSL更新包安装
2. WSL占内存太多 → 配置 .wslconfig 限制资源
3. 环境变量不生效 → 写入 .bashrc 永久生效
4. 找不到gz-harmonic包 → 手动添加Gazebo官方源
5. gz命令不存在 → 单独安装Gazebo本体
6. gazebo_ros包找不到 → 改用新版ros_gz_sim体系

核心提醒：ROS2 Jazzy用的是新版Gazebo Harmonic，集成方式和旧版Gazebo Classic完全不同。网上很多教程已经过时了，遇到问题时多想想"是不是架构变了"。

这是我VLM机器人项目系列的第一篇——环境搭建。接下来会继续更新：

• 第二篇：Qwen2.5-VL-3B模型本地部署与推理
• 第三篇：视觉定位与坐标映射
• 第四篇：模型部署优化（ONNX/TensorRT加速）
• 第五篇：闭环控制系统集成

感兴趣的话可以关注一下，一起踩坑一起进步 🚀

---

如果这篇文章对你有帮助，欢迎点赞、收藏、评论交流！有问题也可以在评论区留言，我会尽力解答。