ROS2 Humble + Gazebo 加载 TurtleBot3 小车失败?—— package:// 与 model:// 的坑

摘要:在 ROS2 Humble + Gazebo classic 11 环境下,用 spawn_entity 把 URDF 小车导入 Gazebo 时,出现“小车无法正常加载/看不见车身”的问题。本文完整记录排查过程,定位到 package:// 与 model:// 两套 URI 协议不对齐 + 缺少 gazebo_model_path 导出 这一根本原因,并给出两种解决方案。


一、问题描述

  • 使用 ROS2 运行 ros2 launch turtlebot3_sim gazebo_spawn.launch.py。
  • 现象:Gazebo 能启动,日志里甚至显示 Successfully spawned entity [turtlebot3],但小车在 Gazebo 里无法正常加载——车身、轮子、激光雷达的视觉模型(mesh)都看不到,只剩碰撞盒或一片空白。
  • 与此同时,/odom、/scan、/imu、/joint_states、/cmd_vel 等话题又都正常,说明物理、关节、传感器其实都在工作。

二、环境信息

项版本
操作系统Ubuntu 22.04(内核 6.8.0)
ROSROS2 Humble
GazeboGazebo classic 11.10.2(不是新版 gz sim / Ignition)
相关包turtlebot3_description、turtlebot3_sim、gazebo_ros

三、排查过程

  1. xacro 展开正常:xacro turtlebot_burger_gazebo.urdf.xacro 能正常生成 URDF,无报错。
  2. robot_state_publisher 正常:能发布 /robot_description(TRANSIENT_LOCAL 锁存 QoS),并成功解析所有 link。
  3. spawn 服务正常:日志显示 SpawnEntity: Successfully spawned entity [turtlebot3],差速驱动插件、关节状态插件都正常加载。
  4. 但 mesh 加载异常:用 gz model --info -m turtlebot3 查看 Gazebo 里最终生成的 SDF,发现 mesh 的路径全被改成了:
filename: "model://turtlebot3_description/meshes/bases/burger_base.stl"

注意:URDF 里写的明明是 package://turtlebot3_description/meshes/...,进 Gazebo 后却变成了 model://。

  1. 路径解析失败:检查 Gazebo 实际使用的 GAZEBO_MODEL_PATH,发现里面只有官方 turtlebot3_gazebo/models,没有 turtlebot3_description。

四、根本原因

问题本质是两套生态、两套 URI 协议没有对齐:

1. package:// 是 ROS 的协议,model:// 是 Gazebo 的协议

  • package://xxx/... 由 ROS 工具(robot_state_publisher、RViz)通过 ament 资源索引解析。
  • Gazebo classic 不认 package://,它只认 model://(走 GAZEBO_MODEL_PATH)、file://、绝对路径。

2. URDF 是 ROS 原生格式,mesh 天然写 package://

URDF 本来就是给 ROS 工具链设计的,mesh 路径用 package:// 对 RViz 完全正确;但对 Gazebo 就不行。

3. gazebo_ros 在 URDF→SDF 转换时把 package:// 重写成 model://

spawn_entity 把 URDF 发给 Gazebo 后,服务端 libgazebo_ros_factory.so 做 URDF→SDF 转换,package://xxx/yyy 被自动改写成 model://xxx/yyy。这一步是自动且躲不掉的。

4. model:// 靠 GAZEBO_MODEL_PATH 解析,而它由各包 package.xml 的导出收集

gazebo_ros 启动时会扫所有包的 package.xml,收集 <gazebo_ros gazebo_model_path="..."> 拼成 GAZEBO_MODEL_PATH。而 turtlebot3_description 的 package.xml 没有这个导出,所以它的目录不在路径里 → model://turtlebot3_description/... 解析不到 → mesh 加载失败。

一句话总结:URDF 里写的是 ROS 的 package://,Gazebo 只认 model://,而 model:// 又没注册路径,两头落空。

五、解决方案

方案 A(推荐,一劳永逸):给 description 包导出 gazebo_model_path

编辑 turtlebot3_description/package.xml,在 <export> 里加一行:

<export>
    <build_type>ament_cmake</build_type>
    <gazebo_ros gazebo_model_path="${prefix}/.."/>
</export>

说明:${prefix} 会被替换成 install/turtlebot3_description/share/turtlebot3_description,/.. 后正好是 install/turtlebot3_description/share/,这样 model://turtlebot3_description/meshes/... 就能解析到 mesh 文件。

然后重新编译并 source:

cd ~/turtlebot3
colcon build
source install/setup.bash
ros2 launch turtlebot3_sim gazebo_spawn.launch.py

方案 B(快速验证,不用重编译):手动加环境变量

export GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:~/turtlebot3/install/turtlebot3_description/share/
ros2 launch turtlebot3_sim gazebo_spawn.launch.py

缺点:每次开新终端都要重新设置。建议先用 B 快速验证,再落地到 A。

六、验证

用 Gazebo 底层 SystemPaths::FindFileURI 验证:

# 不加路径(修复前)→ 解析不到,会一直尝试联网查询,卡死/找不到
# 加上 install/turtlebot3_description/share/ 之后:
FindFileURI(model://turtlebot3_description/meshes/bases/burger_base.stl)
  = /home/lzx/turtlebot3/install/turtlebot3_description/share/turtlebot3_description/meshes/bases/burger_base.stl   ← FOUND

修复后重新启动,Gazebo 里小车车身、轮子、激光雷达的视觉模型即可正常显示。

七、延伸:其他人导入 Gazebo 是怎么处理的

ROS2 生态里主要有这几种做法:

  1. URDF 与 SDF 分离(最标准,官方 TurtleBot3 做法):
  • turtlebot3_description 只放 URDF(package:// mesh),给 RViz / robot_state_publisher 用;
  • turtlebot3_gazebo 另放一套 SDF 模型(model:// mesh),给 Gazebo 用,并在 package.xml 导出 <gazebo_ros gazebo_model_path="${prefix}/models"/>。
  • 原因:URDF 服务 ROS 工具链,SDF 服务 Gazebo 的传感器/插件/材质等更丰富的特性,两者能力不对称。
  1. 给 description 包直接导出 gazebo_model_path(即本文方案 A),适合“想复用同一套 URDF 直接进 Gazebo”。

  2. gazebo_media_path 导出:对应 GAZEBO_RESOURCE_PATH,用于贴图/材质/shadert 等 media 资源,和 model:// 网格不是一回事,别混淆。

  3. 手动设 GAZEBO_MODEL_PATH(本文方案 B,quick-fix)。

  4. 新版 Gazebo(gz sim / Ignition)原生支持 package://:在 ROS2 下通过 ament 直接解析,不再需要这套转换和路径导出;但本文环境是 Gazebo classic 11,用不上。

八、总结

  • 现象是“小车加载不进去”,但物理/传感器其实都正常,缺的是视觉 mesh。
  • 根因是 package://(ROS)→ model://(Gazebo)的自动转换,叠加 gazebo_model_path 未导出,导致 mesh 路径解析不到。
  • 修复只需在 turtlebot3_description/package.xml 加一行 gazebo_model_path 导出即可。
Logo

聚焦RDK与具身智能,汇集机器人开发教程、开源案例和技术交流

更多推荐