ROS2 和 Gazebo 的组合算是目前机器人仿真领域最主流的一套开源方案了。但很多刚接触的朋友第一次搭环境时往往会被各种报错、黑屏、模型加载失败折腾得够呛。这篇内容就是把我自己反复装过十几遍 ROS2 Gazebo 的经验整理出来从版本选择、安装命令、环境变量配置到几个高频坑点的排查思路全部讲清楚。不管你是刚学 ROS2 的小白还是从 ROS1 迁移过来的老手跟着走一遍基本能在几分钟内跑通一个可用的仿真环境并且知道出问题时该往哪个方向查。1. 先把版本这件事定下来别急着敲命令1.1 ROS2 发行版和 Gazebo 版本的对应关系新手最容易犯的错就是随便找个教程就开始装结果 ROS2 和 Gazebo 版本对不上后面各种依赖冲突。ROS2 每个发行版都对 Gazebo 有明确的版本要求这个必须提前确认。目前主流的搭配是这样的ROS2 发行版推荐 Gazebo 版本推荐 Ubuntu 版本HumbleGazebo Classic 11Ubuntu 22.04JazzyGazebo Harmonic (gz-sim 8)Ubuntu 24.04IronGazebo Classic 11 / HarmonicUbuntu 22.04这里有个概念要区分清楚Gazebo Classic和Gazebo新版也叫 Ignition/Gazebo Sim是两个不同的东西。Gazebo Classic 就是老的那个gazebo命令版本号到 11 就停止更新了新版 Gazebo 改名叫gz sim命令是gz。ROS2 Humble 时代两者都能用但到了 Jazzy官方主推的是新版 Gazebo Harmonic。我的建议很直接如果你是新装环境Ubuntu 22.04 就上 Humble Gazebo Classic 11Ubuntu 24.04 就上 Jazzy Gazebo Harmonic。别去折腾混搭除非你有明确的理由。1.2 为什么版本匹配这么重要ROS2 和 Gazebo 之间靠ros_gz新版或gazebo_rosClassic这个桥接包通信。这个桥接包是针对特定版本编译的版本不匹配时轻则话题topic发不出去重则直接段错误崩溃。我踩过的一个典型坑在 Ubuntu 22.04 上装了 Humble然后手贱去 apt 装了最新版 Gazebo Harmonic结果gz sim能单独启动但一挂 ROS2 桥接就报undefined symbol。查了半天才发现是桥接包版本和 Gazebo 版本对不上。后来老老实实卸掉重装 Classic 11一次就通了。所以第一步先确认你的系统版本再决定装哪套。命令很简单lsb_release -a看清楚是 22.04 还是 24.04后面的选择就清晰了。1.3 安装前的系统准备在正式装之前有几件事先做掉能省掉后面一堆麻烦。第一更新系统包索引并且把universe仓库打开ROS2 的包在这个仓库里sudo apt update sudo apt install software-properties-common sudo add-apt-repository universe第二确认 locale 设置正确否则 ROS2 的某些工具会因为编码问题报错locale # 检查输出里是否有 UTF-8如果LANG不是en_US.UTF-8或zh_CN.UTF-8用下面命令设置sudo apt update sudo apt install locales sudo locale-gen en_US en_US.UTF-8 sudo update-locale LC_ALLen_US.UTF-8 LANGen_US.UTF-8 export LANGen_US.UTF-8第三如果你之前装过 ROS1 或者别的 ROS2 版本先把环境变量清理干净。检查~/.bashrc里有没有旧的source /opt/ros/xxx/setup.bash有的话注释掉避免多个版本互相干扰。这个坑很隐蔽有时候你明明装的是 Humble结果终端里ros2 --version显示的是别的版本就是bashrc里残留的 source 语句在作怪。2. 安装 ROS2 和 Gazebo 的完整流程2.1 添加 ROS2 软件源并安装以 Ubuntu 22.04 Humble 为例先添加 ROS2 的 apt 源sudo apt install curl gnupg lsb-release sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(source /etc/os-release echo $UBUNTU_CODENAME) main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null然后更新并安装桌面版包含 RViz2、demo 等工具sudo apt update sudo apt install ros-humble-desktop这里有个选择ros-humble-desktop是完整版包含 GUI 工具ros-humble-ros-base是精简版只有核心库。新手直接上 desktop 版省得后面缺工具再一个个补。安装完成后把环境变量加到bashrcecho source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc验证一下ros2 --version能打印出版本号就说明 ROS2 本体装好了。2.2 安装 Gazebo 和 ROS2 桥接包Humble 对应的 Gazebo Classic 11安装命令sudo apt install ros-humble-gazebo-ros-pkgs这个包会自动把gazebo本体和gazebo_ros桥接一起装上。装完后验证gazebo --version应该显示Gazebo multi-robot simulator, version 11.x.x。如果你用的是 Jazzy Harmonic命令换成sudo apt install ros-jazzy-ros-gz验证用gz sim --version。2.3 环境变量里那几个容易漏的配置装完之后有几个环境变量建议显式设置能避免很多奇怪问题。第一个是GAZEBO_MODEL_PATH告诉 Gazebo 去哪里找模型。如果你后面要加载自定义模型或者网上下载的模型这个必须配export GAZEBO_MODEL_PATH$GAZEBO_MODEL_PATH:~/gazebo_models第二个是GAZEBO_RESOURCE_PATH资源文件路径。一般不用改但如果你把 Gazebo 装到了非标准位置需要指一下。第三个是LIBGL_ALWAYS_SOFTWARE这个跟显卡驱动有关。如果你在虚拟机里跑或者显卡驱动有问题导致 Gazebo 黑屏、闪退可以临时设成 1 强制用软件渲染export LIBGL_ALWAYS_SOFTWARE1注意软件渲染性能很差只适合排查问题用正常跑仿真还是要把显卡驱动装好。这些变量建议都写进~/.bashrc省得每次开终端都要手动设。3. 跑通第一个仿真从空世界到带机器人的场景3.1 启动一个空世界验证基础环境环境装好后先别急着上机器人模型用一个空世界验证一下 Gazebo 能不能正常启动gazebo如果弹出一个带网格地面的窗口说明 Gazebo 本体没问题。这时候你可以试着在左侧面板插入一个简单物体比如一个立方体看看能不能正常显示和交互。如果这一步就黑屏或者闪退先别往下走问题出在图形渲染上。常见原因和排查方向显卡驱动没装好glxinfo | grep OpenGL renderer看看是不是走了软件渲染虚拟机 3D 加速没开在虚拟机设置里把 3D 加速勾上远程桌面连接X11 转发对 OpenGL 支持不好尽量本地跑3.2 用 launch 文件启动 Gazebo 并加载 ROS2 桥接单独启动gazebo命令ROS2 是感知不到的。要让 ROS2 和 Gazebo 通信得通过gazebo_ros提供的 launch 文件启动ros2 launch gazebo_ros gazebo.launch.py这个命令会启动 Gazebo同时把 ROS2 和 Gazebo 的桥接节点拉起来。启动后另开一个终端用下面命令看看话题列表ros2 topic list你应该能看到/clock、/gazebo/...之类的话题。看到这些说明桥接通了。3.3 加载一个带差速驱动的机器人模型空世界跑通后下一步是加载一个真实的机器人模型。这里我用一个常见的两轮差速小车举例说明整个流程。首先创建一个工作空间和功能包mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src ros2 pkg create --build-type ament_cmake my_robot_description然后在功能包里放机器人的 URDF/Xacro 文件、Gazebo 的 world 文件以及一个 launch 文件。launch 文件的核心内容大概是这样from launch import LaunchDescription from launch.actions import IncludeLaunchDescription from launch.launch_description_sources import PythonLaunchDescriptionSource from launch_ros.actions import Node from ament_index_python.packages import get_package_share_directory import os def generate_launch_description(): pkg_share get_package_share_directory(my_robot_description) gazebo_launch IncludeLaunchDescription( PythonLaunchDescriptionSource( os.path.join(get_package_share_directory(gazebo_ros), launch, gazebo.launch.py) ) ) spawn_entity Node( packagegazebo_ros, executablespawn_entity.py, arguments[-topic, robot_description, -entity, my_robot], outputscreen ) return LaunchDescription([gazebo_launch, spawn_entity])这里的关键是spawn_entity.py这个节点它负责把 URDF 描述的机器人模型生成到 Gazebo 世界里。-topic robot_description表示从 ROS2 的robot_description话题读取模型描述。编译并运行cd ~/ros2_ws colcon build source install/setup.bash ros2 launch my_robot_description my_robot.launch.py如果一切正常你会在 Gazebo 里看到小车模型并且可以用ros2 topic pub往/cmd_vel发速度指令让它动起来。3.4 验证机器人是否真的活了模型加载出来不代表就能用。要验证机器人是否真的和 ROS2 打通了做两件事第一检查robot_description话题有没有数据ros2 topic echo /robot_description --once第二发一个速度指令看 Gazebo 里的小车是否移动ros2 topic pub /cmd_vel geometry_msgs/msg/Twist {linear: {x: 0.5}, angular: {z: 0.0}}如果小车动了恭喜你整个链路是通的。如果没动问题可能出在 URDF 里的gazebo_ros_diff_drive插件配置上检查插件里的leftJoint和rightJoint名字是否和 URDF 里的关节名一致。4. 那些年我踩过的坑高频问题排查手册4.1 Gazebo 界面一直闪或者黑屏这是被问得最多的问题没有之一。现象是 Gazebo 窗口打开后不停闪烁或者干脆一片黑。根本原因通常是 OpenGL 渲染问题。排查顺序第一步确认是不是虚拟机。如果是检查虚拟机设置里的 3D 加速有没有开。VMware 和 VirtualBox 都需要在设置里手动开启 3D 加速否则 Gazebo 的 OpenGL 渲染会失败。第二步检查显卡驱动。在物理机上跑glxinfo | grep OpenGL renderer如果显示的是llvmpipe或者softpipe说明在用软件渲染性能极差且容易闪。需要装正确的显卡驱动。NVIDIA 显卡用ubuntu-drivers devices看看推荐驱动然后sudo apt install nvidia-driver-xxx。第三步如果是 NVIDIA 双显卡笔记本可能是用了核显跑 Gazebo。用prime-select query看看当前用的是哪个切到独显sudo prime-select nvidia然后重启。第四步临时应急可以用软件渲染绕过export LIBGL_ALWAYS_SOFTWARE1 gazebo能跑起来说明确实是渲染问题但这不是长久之计。4.2 模型加载失败一直显示 Loading modelGazebo 启动后如果模型一直卡在加载状态或者报Unable to find model基本是模型路径或者网络问题。Gazebo 默认会从在线模型库拉取模型如果网络不通就会一直卡着。解决办法是配置本地模型路径或者提前把模型下载到本地。设置本地模型路径export GAZEBO_MODEL_PATH$GAZEBO_MODEL_PATH:~/.gazebo/models然后把需要的模型放到~/.gazebo/models目录下。每个模型是一个文件夹里面包含model.config和model.sdf。如果你在 launch 文件里指定了 world 文件检查 world 文件里引用的模型 URI 是否正确。常见格式是model://model_name这个model_name必须能在GAZEBO_MODEL_PATH里找到。4.3 ROS2 话题发不出去Gazebo 里没反应这个问题的排查链路比较长我一般按下面的顺序查先确认桥接节点是否在跑ros2 node list应该能看到/gazebo相关的节点。如果没有说明gazebo_ros没启动成功检查 launch 文件里有没有包含gazebo.launch.py。再确认话题是否对得上ros2 topic list ros2 topic info /cmd_vel看看/cmd_vel的发布者和订阅者数量。如果订阅者是 0说明 Gazebo 那边的插件没订阅这个话题检查 URDF 里插件的rosremapping配置。最后确认消息类型是否匹配。ROS2 里cmd_vel的类型是geometry_msgs/msg/Twist如果你发的是别的类型Gazebo 收不到。4.4 spawn_entity 报 entity already exists这个错误通常是因为你重复启动了 launch 文件上一次的模型还没被清理掉。解决办法有两个一是重启 Gazebo最简单粗暴。二是在 launch 文件里加一个删除实体的步骤或者用-entity参数换个名字。我一般习惯在调试时给实体名加个时间戳避免冲突import time entity_name fmy_robot_{int(time.time())}4.5 编译时报 package not foundcolcon build时如果报找不到某个包先确认依赖有没有装全rosdep install --from-paths src --ignore-src -r -yrosdep会自动解析package.xml里的依赖并安装。如果rosdep本身没初始化先跑sudo rosdep init rosdep update还有一个常见原因是source顺序不对。工作空间的setup.bash必须在 ROS2 的setup.bash之后 source否则找不到 ROS2 的基础包。5. 让仿真更接近真实几个进阶配置5.1 用 Xacro 管理复杂的机器人模型URDF 写复杂机器人时会非常冗长Xacro 是 URDF 的宏语言支持变量、条件、复用。强烈建议机器人模型都用 Xacro 写然后在 launch 文件里转成 URDF。转换命令xacro robot.urdf.xacro robot.urdf在 launch 文件里可以用Command动作动态转换from launch.substitutions import Command robot_description Command([xacro , os.path.join(pkg_share, urdf, robot.urdf.xacro)])这样改模型不用手动转换launch 时自动处理。5.2 配置物理引擎参数Gazebo 默认的物理引擎参数对某些场景不够真实比如摩擦力、关节阻尼。可以在 world 文件里调整physics typeode max_step_size0.001/max_step_size real_time_factor1.0/real_time_factor real_time_update_rate1000/real_time_update_rate /physicsmax_step_size越小仿真越精确但越慢。一般 0.001 秒够用。real_time_factor是仿真时间和真实时间的比例1.0 表示实时。如果仿真跑起来很卡先把max_step_size调大试试比如 0.002 或 0.005。5.3 传感器插件的配置要点Gazebo 里常用的传感器插件有激光雷达、摄像头、IMU。配置时最容易出问题的是话题名和坐标系。以激光雷达为例插件配置里要指定frameName这个必须和 URDF 里的 link 名字一致否则 RViz2 里显示会错位。另外topicName建议用相对话题名比如scan这样会自动加上命名空间。摄像头插件要注意imageTopicName和cameraInfoTopicName两个话题都要配否则 RViz2 里只能看到图像但拿不到相机内参。5.4 在虚拟机里跑仿真的性能优化很多人是在虚拟机里学 ROS2 的虚拟机跑 Gazebo 性能确实是个问题。几个优化方向给虚拟机多分点 CPU 核心和内存至少 4 核 8G开启 3D 加速降低 Gazebo 的渲染质量在 Gazebo 设置里把阴影、抗锯齿关掉用gzserver单独跑物理仿真gzclient单独跑界面调试时可以只开 servergzserver world_file.world gzclient这样界面卡的时候物理仿真不受影响。6. 从仿真到实机的衔接思路仿真跑通之后下一步通常是把仿真里验证过的算法往实机上迁。这里有几个经验点值得提前注意。第一仿真里的传感器是理想的实机有噪声。所以算法在仿真里跑通不代表实机能用得留出调参的余地。比如激光雷达的噪声模型仿真里可以加高斯噪声模拟真实情况。第二仿真里的时间系统和实机不一样。Gazebo 用/clock话题发布仿真时间实机用的是系统时间。如果你的代码里用了ros2::Time要确保use_sim_time参数设置正确。仿真时设为true实机设为false。第三坐标系标定。仿真里机器人的各个 link 位置是精确的实机上需要做手眼标定、IMU 标定。这部分工作仿真帮不上忙但可以在仿真里先把标定流程跑一遍熟悉操作。第四控制频率。仿真里可以跑很高的控制频率实机上受限于通信和计算频率要降下来。建议在仿真里就把控制频率设成和实机一致避免迁移时出现控制不稳定。我自己的习惯是仿真环境里就把参数配置和实机对齐包括话题名、坐标系、控制频率。这样从仿真切到实机时只需要改use_sim_time和硬件接口算法部分基本不用动。Gazebo 的仿真环境搭建说到底就是版本匹配、依赖装全、环境变量配对这三件事。把这三件事做扎实后面 90% 的报错都能避免。剩下的 10%靠的是遇到问题时知道往哪个方向查——是渲染问题、路径问题还是话题通信问题。这篇内容里列的排查链路都是我在实际项目里一条条试出来的希望能帮你少走点弯路。