ROS 2 与 Gazebo 版本对齐实战：从 REP-2000 到可运行仿真

1. 项目概述：为什么今天还要认真搭一遍 Gazebo 仿真环境？

你手头刚买回一块 Jetson Orin 或者正调试着 ROS 2 Humble 的新工控机，想先在电脑上把机械臂的运动规划跑通、把激光雷达的 SLAM 流程理顺、或者验证下自定义底盘的 PID 控制器参数——这时候， Gazebo 不是“可选项”，而是你开发链路上不可跳过的安全气囊 。它不是玩具，而是一套经过工业级验证的物理仿真引擎，能真实模拟重力、摩擦、碰撞响应、传感器噪声、甚至电机惯性与带宽限制。我带过三届机器人方向的毕设学生，凡是跳过 Gazebo 直接上真机的，90% 都在第二周撞坏过轮毂编码器或烧过驱动板。这不是危言耸听，是实测数据。

关键词里那个 L5 | Tutorials > Advanced > Simulators > Gazebo > Setting up a robot simulation (Gazebo) ，表面看是个文档路径，背后其实是一条成熟开发者的隐性能力图谱：它要求你同时理解 ROS 2 的节点通信机制、Gazebo 的 SDF 模型描述规范、系统级依赖的版本耦合逻辑，以及最关键的—— 如何让两个庞大生态在同一个 Linux 环境里不打架 。很多人卡在 gz sim 命令报错、 ros2 launch 找不到插件、或者模型加载后悬空漂浮，根本原因不是命令敲错了，而是没搞懂 ROS 2 和 Gazebo 的“握手协议”到底在哪一层完成。这篇内容，就是帮你把这套协议拆开、摊平、用螺丝刀拧紧每一个接口。它不讲“怎么安装”，而是讲“为什么必须这样装”；不列命令清单，而是告诉你每个命令执行后，系统底层发生了什么变化；不回避报错，而是带你从日志第一行开始逆向定位。适合已经写过几个 ROS 2 节点、但第一次接触仿真环境的开发者，也适合被客户临时拉去调试现场、发现仿真和实机行为不一致的工程师。你不需要记住所有参数，但读完后，应该能自己判断出：当 Gazebo 启动失败时，该查 /opt/gz 还是 $AMENT_PREFIX_PATH ，该重装 gazebo_ros_pkgs 还是检查 libignition-gazebo6-dev 的 ABI 版本。

2. 核心设计思路：为什么必须区分 Gazebo Classic 和 Ignition？版本对齐不是玄学

2.1 一次彻底的命名革命：从 Gazebo Classic 到 Ignition 再到 Gazebo（新）

很多初学者看到官方文档里反复出现 “Gazebo (previously known as Ignition)” 这句话会困惑：这到底是改名了还是套壳了？答案是： 这是一次底层架构的彻底重构，不是简单的品牌升级 。Gazebo Classic（即旧版 Gazebo 9/11）基于 ODE 物理引擎和 SDF 1.4/1.6 描述语言，其 ROS 1 插件（ gazebo_ros ）通过 libgazebo_ros_api_plugin.so 直接挂钩 Gazebo 的 C++ API。而 Ignition（2018 年启动）是全新编写的模块化框架，核心组件包括 ign-gazebo （仿真主程序）、 ign-physics （物理引擎抽象层）、 ign-sensors （传感器模拟）等，采用现代 C++17 编写，支持多线程物理计算和更精细的传感器建模。2023 年，Ignition 项目正式将主程序 ign-gazebo 更名为 gz sim ，并统称整个生态为 Gazebo （注意：这是新 Gazebo，不是旧版）。这个更名不是营销噱头，而是标志着 ROS 2 官方已将 Ignition 系列作为唯一推荐的仿真后端。如果你现在还在用 gazebo 命令（对应 /usr/bin/gazebo ），那大概率是旧版 Classic，它与 ROS 2 的兼容性极差，甚至无法加载 .sdf 文件中的 <plugin> 标签——因为新版插件接口完全重写了。

提示：执行 which gazebo 和 which gz 是最快速的判别方式。前者指向 /usr/bin/gazebo （Classic），后者指向 /usr/bin/gz （新 Gazebo）。二者共存于同一系统是常见现象，但绝不能混用。我见过最典型的错误，是在 ROS 2 Humble 环境下 source /opt/ros/humble/setup.bash 后，又手动 export GAZEBO_PLUGIN_PATH=/usr/lib/x86_64-linux-gnu/gazebo-11/plugins ，结果 gz sim 启动时疯狂报 Plugin not found ——因为路径里指向的是 Gazebo 11 的插件，而 gz sim 只认 ignition-gazebo6 编译的插件。

2.2 ROS REP-2000：版本对齐的“宪法性文件”

ROS 社区用 REP-2000 （ROS Enhancement Proposal）来标准化各 ROS 发行版默认绑定的 Gazebo 版本。这不是建议，而是构建工具链的硬性约束。以 ROS 2 Humble 为例，REP-2000 明确规定其默认 Gazebo 版本为 Ignition Gazebo 6 （对应 gz sim 命令的 v6.x 系列）。这个“6”不是随意编号，它代表了 ABI（Application Binary Interface）的主版本号。 ignition-gazebo6 编译的插件，只能被 gz sim v6.x 加载；若你手动安装了 ignition-gazebo7 ，那么所有为 v6 编译的 ROS 2 插件（如 gazebo_ros_control ）将直接失效，因为 libignition-gazebo7-core.so 与 libignition-gazebo6-core.so 的符号表不兼容。这就像给 Windows 10 的 exe 文件强行用 Windows 11 的运行库去加载——必然崩溃。因此，“安装 Gazebo” 的第一步，从来不是 sudo apt install ignition-gazebo6 ，而是 确认你的 ROS 2 版本，并严格遵循 REP-2000 查表 。Humble 对应 Gazebo 6，Foxy 对应 Gazebo 4，Jazzy 对应 Gazebo 8。这个表不是藏在某个角落的文档里，而是直接集成在 rosdep 的源码中：当你执行 rosdep install --from-paths src --ignore-src -r -y 时， rosdep 就是根据 REP-2000 的映射关系，自动为你解析出 ignition-gazebo6 这个包名。

注意：不要迷信 apt list | grep ignition 的输出。Ubuntu 22.04 的官方源里同时存在 ignition-gazebo5 和 ignition-gazebo6 ，但只有 ignition-gazebo6 是 Humble 的官方支持版本。安装错误版本的后果，不是“功能缺失”，而是“静默失败”——模型能加载，但关节控制器无响应，或者激光数据永远为零。这种问题排查起来极其耗时，因为日志里不会明确提示“版本不匹配”，只会显示 Failed to load plugin 这类模糊信息。

2.3 工作空间设计：为什么 colcon build 必须包含 gazebo_ros_pkgs

一个常见的误解是：“Gazebo 是系统级软件，ROS 2 包只是调用它，所以我的工作空间里不需要编译 Gazebo 相关的 ROS 包”。这是致命错误。 gazebo_ros_pkgs （包含 gazebo_ros , gazebo_ros_control , gazebo_ros_pkgs 等子包）不是简单的“胶水代码”，它们是 ROS 2 和 Gazebo 之间的双向翻译器 。 gazebo_ros 提供了 spawn_entity.py <