ROS2 Humble与Gazebo Harmonic仿真环境搭建：gz_ros2_control兼容性实战指南

去年年底我把仿真环境从 Gazebo Classic 11 迁到 Gazebo Harmonic也就是 gz-sim 8.x时是真真切切体会了一把什么叫ROS2 Humble 和 gz_ros2_control 兼容性是玄学。Humble 作为 LTS 版本官方推荐搭档是 Gazebo Classic 11而 Harmony 这边又把 gz_ros2_control 插件接口改了个底朝天导致大量老司机在这套组合上翻车。这篇文章我从踩坑者角度把从零搭建到仿真机器人真正动起来的完整过程、所有报错和修复方式都记录下来。适合想用 Humble Harmonic 做仿真、但被官方支持矩阵吓退的工程师和学生内容不绕弯子直接给结论、给命令、给配置。1. 版本时间线为什么 Humble 和 Harmonic 天生不搭1.1 官方支持矩阵的真相先看清这张官方支持矩阵。ROS2 Humble 发布于 2022 年 5 月是长期支持版本维护到 2027 年而 Gazebo Harmonic 在 2023 年年底才正式成为 Gazebo 主线版本。问题在于Humble 发布时 Harmonic 还在开发中gazebo_ros_pkgs的 Humble 分支当时默认支持的是 Gazebo Fortressgz-sim 6和 Gazebo Classic 11。所以ROS2 Humble Gazebo Harmonic严格来说不在官方铺设的常规轨道上。官方文档里如果你去查支持矩阵大概率得到的答案是不支持。但这不代表跑不通只要把接口层捋顺这两者完全可以共存。我自己的经验是Humble 的稳定性 Harmonic 的渲染效果组合起来做机器人算法验证非常舒服值得花时间搞定。1.2 接口层到底卡在哪里接口层的冲突集中在三个点第一是传输层。Harmonic 依赖 gz-transport 13ROS2 Humble 自带的是基于 DDS 的 rclcpp 抽象两者通过 gz-transport 接口沟通时版本必须对齐。如果 apt 源里的 gz-transport 版本不对最常见的表现就是节点启动时报版本错误。第二是模型描述层。Harmonic 采用 SDFormat 1.10老版本的 URDF 解析和 SDF 生成都会受影响。尤其是你在 URDF 里如果写了老式的gazebo扩展标签在 Harmonic 里解析逻辑会发生变化。第三是插件加载层。gazebo_ros_pkgs仓库中针对 gz-sim 的 ros2_control 实现是gz_ros2_control它直接调用 gz-sim 的 World、Sensor、Entity API。这套 API 从 gz-sim 6.0Fortress到 8.0Harmonic大体一致但头文件路径和类名变化不小。直接通过 apt 装一个gazebo_ros_pkgs的 humble 包是找不到支持 gz-sim 8 的gz_ros2_control插件的。1.3 为什么还有人坚持用这个组合既然官方不支持为什么还硬上我的理由有三个一是 Harmonic 的渲染和物理引擎比 Classic 强太多PBR 材质、更稳定的物理求解器对做感知和导航的人来说体验差距明显二是 Classic 已经进入维护模式新功能不再加长期看迁移是必然三是很多新发布的仿真世界模型比如各类机器人厂商的官方仿真包已经默认跑在 Harmonic 上了绕不开。2. 环境搭建apt、源码和三个大坑2.1 Ubuntu 22.04 安装 ROS2 Humble这一步是最稳的Ubuntu 22.04 安装 ROS2 Humble 的流程已经非常成熟直接按官方步骤来sudo apt update sudo apt install -y locales sudo locale-gen en_US en_US.UTF-8 sudo apt install -y software-properties-common sudo add-apt-repository universe sudo apt update sudo apt install -y curl 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 $(. /etc/os-release echo $UBUNTU_CODENAME) main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null sudo apt update sudo apt upgrade -y sudo apt install -y ros-humble-desktop ros-dev-tools装完记得初始化 rosdepsudo rosdep init rosdep update echo source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc这里要提醒一句不要装 ros-humble-desktop-full里自带的旧版 Gazebo Classic 依赖组否则后面会和 Harmonic 产生库冲突。如果你已经装了后面处理起来会麻烦一些但也不是无解。2.2 安装 Gazebo Harmonic别再 snap 了Harmonic 有几种安装方式snap、源码编译、OGRC apt 仓库。我最推荐 apt 仓库方式原因只有一个snap 的隔离机制会导致它和 ROS2 的 DDS 通信经常出幺蛾子而且 snap 内的文件系统布局会让调试变得很痛苦。OGRC apt 仓库安装流程sudo wget https://packages.osrfoundation.org/gazebo.gpg -O /usr/share/keyrings/pkgs.osrfoundation.org.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/pkgs.osrfoundation.org.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main | sudo tee /etc/apt/sources.list.d/gazebo-stable.list sudo apt update sudo apt install -y gz-harmonic安装完成后验证gz sim --version如果输出类似Gazebo Simulator version 8.x.x说明装好了。同时你还应该确认配套的libgz-sim8-dev和libgz-transport13-dev是否已安装这两个是后续源码编译的关键依赖dpkg -l | grep libgz-sim8 dpkg -l | grep libgz-transport132.3 三个大坑库冲突、缺 dev 包、rosdep 解析失败坑一与 Gazebo Classic 的库冲突。如果你之前装过gazebo11那系统里可能存在/usr/lib/x86_64-linux-gnu/libsdformat.so和 Harmonic 的 SDFormat 版本冲突。具体表现是你启动 Harmonic 时提示libsdformat.so.12: undefined symbol或者加载 URDF 时 SDF 解析报错。我的处理方式是把 Gazebo Classic 的 ros 相关依赖整体卸载sudo apt remove -y gazebo11 libgazebo11-dev ros-humble-gazebo-* sudo apt autoremove -y坑二缺 dev 包导致编译到一半报找不到头文件。gz-harmonic这个元包只装运行库你要编译gz_ros2_control还需要一堆-dev包。建议一次性装齐sudo apt install -y libgz-sim8-dev libgz-transport13-dev libgz-msgs9-dev libgz-math7-dev libsdformat13-dev坑三rosdep 在源码编译时解析 gz 的依赖失败。rosdep默认不会去找 OGRC 仓库的包容易在rosdep install时卡住。解决办法是手动安装这些依赖或者在.bashrc中导出ROS_OS_OVERRIDEubuntu:22.04并在/etc/ros/rosdep/sources.list.d/20-default.list中确认源没坏。如果还是不行直接跳过 rosdep手动 apt 安装缺失的库即可。3. 源码编译 gz_ros2_control看懂那堆红色报错3.1 为什么不能直接 apt 安装在 Humble 的 apt 源里ros-humble-gazebo-ros-pkgs带的是针对 Gazebo Classic 和 Fortress 的gazebo_ros2_control。即使你强行装上了它链接的也是gz-sim6的库和 Harmonic 的gz-sim8完全对不上。所以要走源码编译这条路。3.2 clone 分支和编译前准备先建一个工作空间然后 clonegazebo_ros_pkgs的 humble 分支mkdir -p ~/gz_ws/src cd ~/gz_ws/src git clone -b humble https://github.com/ros-simulation/gazebo_ros_pkgs.git编译前有一个关键环境变量GZ_VERSION。gazebo_ros_pkgs的 CMake 逻辑会读取这个变量来决定链接哪个 gz-sim 版本。网上很多教程没提这个导致编译时去链接 gz-sim6报一堆GZ_TRANSPORT_VERSION不匹配。export GZ_VERSIONharmonic这个变量不能只当前终端生效最好写进.bashrcecho export GZ_VERSIONharmonic ~/.bashrc source ~/.bashrc然后安装依赖sudo apt install -y python3-vcstool python3-colcon-common-extensions cd ~/gz_ws rosdep install --from-paths src --ignore-src -r -y --skip-keysgz-sim8因为我前面已经手动装了所有gz相关 dev 包这里--skip-keys跳过即可。3.3 编译命令和常见报错编译的时候只选gz_ros2_control以及依赖的包避免整个 workspace 一起编译浪费时间cd ~/gz_ws colcon build --symlink-install --packages-select gz_ros2_control --cmake-args -DCMAKE_BUILD_TYPERelease如果一切顺利你会看到Summary: 1 package finished。如果不顺利下面这些报错是我真的遇到过的直接给解决方案报错1Could not find a package configuration file provided by gz-sim8说明 CMake 找不到 gz-sim8 的 config。原因是GZ_VERSION环境变量没生效或者gz-sim8_DIR指向错误。排查echo $GZ_VERSION ls /usr/lib/x86_64-linux-gnu/cmake/gz-sim8/gz-sim8-config.cmake如果有这个文件但 CMake 还是找不到手动指定colcon build --symlink-install --packages-select gz_ros2_control --cmake-args -DCMAKE_BUILD_TYPERelease -Dgz-sim8_DIR/usr/lib/x86_64-linux-gnu/cmake/gz-sim8报错2fatal error: gz/transport/Node.hh: No such file or directory缺libgz-transport13-dev。装完继续编译即可。报错3undefined reference to ... gz::sim8::...这类链接错误通常是 workspace 里同时存在旧版本gz_ros2_control编译产物导致的。清理重新编译rm -rf build/ install/ log/ colcon build --symlink-install --packages-select gz_ros2_control报错4protobuf version mismatchHarmonic 依赖的 gz-msgs9 与 ROS2 Humble 自带的 protobuf 版本有冲突。在 Ubuntu 22.04 上protobuf 版本一般是 3.21Harmonic 的 gz-msgs9 能兼容。如果出现版本不匹配先查一下protoc --version dpkg -l | grep protobuf确认是 3.21 版本后问题基本出在 CMake 缓存上删掉 build 目录重新配置即可。3.4 编译后验证source ~/gz_ws/install/setup.bash ros2 pkg prefix gz_ros2_control如果输出一个路径说明包已经可用。你也可以直接看插件库文件是否存在find ~/gz_ws/install -name libgz_ros2_control*.so这个.so文件就是后面 URDF 里要引用的插件本体。4. URDF 与插件配置把 ros2_control缝到仿真世界4.1 从 ros2_control 架构理解插件的角色ros2_control的核心思路是控制器管理器controller_manager加载各种控制器joint_state_broadcaster、diff_drive_controller 等控制器通过硬件接口hardware interface读写机器人状态。在 Gazebo 仿真里这个硬件接口就是由gz_ros2_control/GazeboSimSystem插件充当的。它订阅仿真世界的关节状态把数据喂给 ros2_control同时接收控制指令写入仿真关节。所以整个链路是控制器管理器 → 控制器 → GazeboSimSystem 硬件接口插件 → gz-sim 关节理解了这个链路配置起来就有章法了。4.2 一个最小可运行的 URDF 示例下面是我的测试机器人 URDF两个轮子加一个底座足够验证差速驱动?xml version1.0? robot nametest_rover xmlns:xacrohttp://www.ros.org/wiki/xacro link namebase_link inertial mass value2.0/ inertia ixx0.01 ixy0.0 ixz0.0 iyy0.01 iyz0.0 izz0.01/ /inertial visual geometrybox size0.4 0.3 0.1//geometry /visual collision geometrybox size0.4 0.3 0.1//geometry /collision /link link nameleft_wheel inertial mass value0.2/ inertia ixx0.0001 ixy0.0 ixz0.0 iyy0.0001 iyz0.0 izz0.0002/ /inertial visual geometrycylinder radius0.1 length0.05//geometry origin rpy0 1.5708 0/ /visual collision geometrycylinder radius0.1 length0.05//geometry origin rpy0 1.5708 0/ /collision /link link nameright_wheel inertial mass value0.2/ inertia ixx0.0001 ixy0.0 ixz0.0 iyy0.0001 iyz0.0 izz0.0002/ /inertial visual geometrycylinder radius0.1 length0.05//geometry origin rpy0 1.5708 0/ /visual collision geometrycylinder radius0.1 length0.05//geometry origin rpy0 1.5708 0/ /collision /link joint nameleft_wheel_joint typecontinuous parent linkbase_link/ child linkleft_wheel/ origin xyz0 0.2 0.05/ axis xyz0 1 0/ /joint joint nameright_wheel_joint typecontinuous parent linkbase_link/ child linkright_wheel/ origin xyz0 -0.2 0.05/ axis xyz0 1 0/ /joint ros2_control nameGazeboSystem typesystem hardware plugingz_ros2_control/GazeboSimSystem/plugin /hardware joint nameleft_wheel_joint command_interface namevelocity/ state_interface nameposition/ state_interface namevelocity/ /joint joint nameright_wheel_joint command_interface namevelocity/ state_interface nameposition/ state_interface namevelocity/ /joint /ros2_control gazebo plugin filenamelibgz_ros2_control-system.so namegz_ros2_control::GazeboSimSystem parameters$(find test_rover)/config/controllers.yaml/parameters /plugin /gazebo /robot注意${find test_rover}是 xacro 宏实际使用前需要替换成真实包路径。4.3 为什么用 typesystem 而不是 actuator很多新手会问差速轮不是应该用typeactuator吗实际上gz_ros2_control的GazeboSimSystem插件是一个系统级硬件接口它一次性处理所有关节的读写而不是每个关节一个 actuator。所以typesystem是标准写法。如果你非要拆成多个 actuatorgz_ros2_control在写read()/write()时的生命周期管理会变得异常复杂没必要。4.4 controllers.yaml 配置controller_manager: ros__parameters: update_rate: 50 joint_state_broadcaster: ros__parameters: extra_joints: - left_wheel_joint - right_wheel_joint diff_drive_controller: ros__parameters: left_wheel_names: [left_wheel_joint] right_wheel_names: [right_wheel_joint] wheel_separation: 0.4 wheel_radius: 0.1 use_stamped_vel: false publish_rate: 50 base_frame_id: base_link odom_frame_id: odom enable_odom_tf: true这里wheel_separation一定要和 URDF 里两个轮子的 Y 间距一致否则转向会偏。URDF 里left_wheel_joint的 origin y0.2right_wheel_joint的 origin y-0.2所以轮距是 0.4和配置一致。4.5 gazebo_ros2_control 与 gz_ros2_control 的配置差异如果你以前用的是经典 Gazebo 的gazebo_ros2_control迁移到 Harmonic 时最容易漏掉的是 URDF 里插件filename的变化。经典版是libgazebo_ros2_control.soHarmonic 版是libgz_ros2_control-system.so名字里多了-system对应它的系统硬件接口身份。在plugin标签里也可以显式加上robot_param_node之类的参数但我测试下来默认配置就够用。5. 启动联调与验证从 spawn 到 /cmd_vel5.1 准备 launch 文件我习惯用一个 launch 文件来启动整个仿真环境而不是手动开一堆终端。下面这个 launch 完成三件事启动 Harmonic 空世界、生成机器人、加载控制器。from launch import LaunchDescription from launch.actions import ExecuteProcess from launch_ros.actions import Node from launch_ros.substitutions import FindPackageShare from launch.substitutions import Command, FindExecutable from launch_ros.parameter_descriptions import ParameterValue import os def generate_launch_description(): pkg_share FindPackageShare(test_rover).find(test_rover) urdf_path os.path.join(pkg_share, urdf, test_rover.urdf) world_path os.path.join(pkg_share, worlds, empty.sdf) controllers_path os.path.join(pkg_share, config, controllers.yaml) robot_description ParameterValue( Command([FindExecutable(namexacro), , urdf_path]), value_typestr ) return LaunchDescription([ ExecuteProcess( cmd[gz, sim, -r, world_path], outputscreen ), Node( packageros2_control, executablespawner, arguments[joint_state_broadcaster, --controller-manager, /controller_manager], outputscreen ), Node( packageros2_control, executablespawner, arguments[diff_drive_controller, --controller-manager, /controller_manager], outputscreen ), ])这里有个细节-r参数让仿真启动后直接运行不加的话仿真会暂停控制器加载了也不会动。新手经常卡在这一步比如节点都启动了/cmd_vel也有发布但轮子就是不动先去检查 Harmonic 世界是不是在运行状态GUI 左下角的播放键是不是没按。5.2 spawn 机器人到 Harmonic 世界把 URDF 加载到 Harmonic 里可以用官方给的 spawn_entity 节点。在gazebo_ros_pkgs中对应的可执行文件是gz_spawn_entity.pysource ~/gz_ws/install/setup.bash ros2 run gz_ros2_control test_spawner如果没有现成的 spawner也可以直接用ros2 run gz_sim gz_spawn_entity.py里的泛化节点。确保在 spawn 之前先启动robot_state_publisherros2 run robot_state_publisher robot_state_publisher --ros-args -p robot_description:$(xacro ~/your_robot.urdf)这个节点不启动后面 rviz 和 TF 都会有问题。5.3 启动控制器并检查状态控制器用spawner加载最稳妥ros2 control load_controller joint_state_broadcaster ros2 control load_controller diff_drive_controller ros2 control set_controller_state joint_state_broadcaster active ros2 control set_controller_state diff_drive_controller active或者直接用spawner一次性搞定ros2 run ros2_control spawner joint_state_broadcaster diff_drive_controller加载后检查ros2 control list_controllers正常会看到两个active状态的控制器。接着在一个终端发布速度指令ros2 topic pub /cmd_vel geometry_msgs/msg/Twist {linear: {x: 0.5}, angular: {z: 0.0}}此时切到 Gazebo GUI如果两个轮子开始向前转动说明整条链路已经打通。5.4 时间同步问题gz_ros2_control有一个特殊之处它直接通过 gz-transport 与仿真通信时钟同步不像 Classic 那样依赖 ROS2 topic/clock。但如果你的控制器算法里用到了use_sim_time还是得把 Harmonic 的时间桥接到 ROS2ros2 run ros_gz_bridge parameter_bridge /clockrosgraph_msgs/msg/Clock[gz.msgs.Clock对于打开use_sim_time:true的节点比如 slam_toolbox、nav2这个桥接必不可少。否则你会看到 TF 和仿真时间对不上表现为机器人原地打转但 map 不变。5.5 验证关节状态ros2 topic echo /joint_states如果输出里left_wheel_joint和right_wheel_joint的position和velocity数值在变化说明状态反馈链路正常。同时ros2 topic echo /odom应该有线速度和角速度数据。我实际调试中遇到过一个问题/odom有数据但/joint_states不动。排查下来是插件里read()没被调用原因是update_rate设置过低仿真步长大于控制器刷新间隔导致部分帧被跳过。把controller_manager的update_rate提到 50 后解决。6. 高频踩坑实录这些问题不解决教程会卡你三天6.1 编译产物被覆盖如果你同时在工作空间里保留有gazebo_ros2_control经典版和gz_ros2_controlHarmonic 版colcon 可能把两个包的install/lib下的.so文件混着放。最后 URDF 加载插件时报Failed to load plugin: libgz_ros2_control-system.so但文件明明存在。解决办法是只编译gz_ros2_control一个包并把之前经典版的install目录清掉。6.2/controller_manager没启动gz_ros2_control插件本身不创建/controller_manager它只是硬件层。你必须在 launch 文件里显式启动controller_manager节点ros2 run controller_manager controller_manager --ros-args -p robot_description:$(xacro ~/your_robot.urdf)或者把controller_manager加进 launchNode( packagecontroller_manager, executableros2_control_node, parameters[{robot_description: robot_description}, controllers_path], outputscreen )6.3 Harmonic 世界加载太慢导致 controller 提前加载失败Harmonic 首次启动会编译渲染资源缓存耗时超出spawner默认重试时间时会报 controller 加载失败。这不算 bug解决办法是在 launch 里加一个比较长的spawner重试时间或者用--controller-manager-timeout 60ros2 run ros2_control spawner diff_drive_controller --controller-manager-timeout 606.4 URDF 里${find ...}没替换xacro 是自动替换${find}的但如果你直接在 launch 里用Command([xacro urdf_path])xacro 需要正确设置ament_prefix_path或ROS_PACKAGE_PATH才能找到自定义包。如果 launch 文件在自定义包中运行一般没问题但如果从别的目录启动容易报package xxx not found。建议在 launch 里写成robot_description ParameterValue( Command([xacro , urdf_path]), value_typestr )并且确保urdf_path用的是FindPackageShare解析出的绝对路径不走相对路径。6.5 物理引擎参数导致轮子陷地Harmonic 默认物理引擎是 DART接触摩擦参数和 Classic 不完全一样。如果你的机器人模型没有 proper 的 collision 几何或者摩擦系数为 0发布cmd_vel后轮子会空转但机器人不动。检查 URDF 里 collision 是否和 visual 对齐必要时在 SDF 中显式指定friction. 我这里吃过亏visual 里给了圆柱体collision 给了个 box轮子一落地就卡住。6.6 环境变量的坑GZ_VERSIONharmonic这个变量不光影响编译也影响运行时。如果运行时没设置插件找 lib 时会默认找 gz-sim6 相关的库报错信息通常类似[ERROR] [gz_ros2_control]: Failed to load entity or component所以.bashrc里保险起见把下面三行都加上export GZ_VERSIONharmonic export GZ_SIM_SYSTEM_PLUGIN_PATH$HOME/gz_ws/install/lib source /opt/ros/humble/setup.bash source $HOME/gz_ws/install/setup.bash6.7 多版本共存时的库优先级系统里如果还有 Fortress 或 Classic 的残留库ldconfig的优先级可能导致运行时报错。用LD_LIBRARY_PATH强制指定 Harmonic 库路径export LD_LIBRARY_PATH/usr/lib/x86_64-linux-gnu/gz-sim8:$LD_LIBRARY_PATH这个方法在 gazebo_ros_pkgs 老版本和新版本混装的机器上特别管用。7. 这组环境后续还能怎么用Harmonic Humble 这套组合跑通之后你的开发体验会有一个质的提升。我目前在这套环境上同时跑过 Nav2 导航栈和 slam_toolbox 建图没有任何明显的性能瓶颈。后续如果你也打算长期用建议把整个~/gz_ws做一次 Docker 镜像快照或者至少写一个自动安装脚本免得重装系统时重新踩一遍这么多坑。如果你做控制算法研究还可以在这个基础上加装 ros2_control 的模拟硬件层把 Gazebo 换成自己写的纯数据源做 HIL 测试这也是 ros2_control 设计上的一大优势。另外Harmonic 的 Sensor API 支持多相机拼接、IMU 噪声注入等高级配置后续做感知仿真也有很大想象空间。最后分享一个实际经验这套环境跑通之后我建议你在controllers.yaml里把diff_drive_controller的publish_rate和odom的 TF 频率保持一致并且保证update_rate不低于仿真步长频率否则时间一长会出现明显的里程计漂移。这个细节在官方文档里没有明确强调但我在长时间跑导航任务时感受非常明显。