Gazebo模型搭建与修改实战：从SDF到ROS 2联调

Gazebo仿真平台的模型搭建与修改，看着是个老话题，但最近问的人特别多，尤其是大家都在折腾Ubuntu 24.04配ROS 2 Jazzy加Gazebo Harmonic这套新组合之后。我最初接触Gazebo那会儿，天真的以为往场景里拖几个现成模型就算会用了，结果真到做项目时，想改传送带速度、给机械臂换个摄像头视角、调一下机器人的碰撞体积，全都无从下手。

这篇文章会把我在实际项目里积累的模型搭建和修改经验完整整理出来。从模型文件结构开始讲，再手把手带大家从零写一个能跑的传送带模型，然后覆盖日常最常用的修改套路和排错经验，最后聊聊Gazebo与ROS 2联调时跑SLAM、加载二维码这些进阶玩法。无论你是刚进仿真坑的新手，还是已经在跑demo但控制不好模型的进阶玩家，这篇文章都能给你一些真正用得上的东西。

1. 为什么说模型文件是整个Gazebo仿真项目的根基

1.1 Gazebo里的模型不是"好看的外观"，是物理实体

很多人第一次打开Gazebo时，以为它就是个三维可视化工具，模型就是拖进去的一个个漂亮3D对象。这个认知会在你真正做仿真时给你带来巨大的麻烦。

在Gazebo中，一个模型（Model）是物理引擎中的一个实体。它身上挂载着质量、惯性、碰撞形状、关节约束、传感器，甚至还有插件（Plugin）来模拟电机控制、摩擦、气动等行为。你看到的可视化网格（Visual Mesh）只是整个模型最表层的一层皮，真正参与物理计算的是碰撞几何（Collision），真正决定运动响应的是惯性参数（Inertial），真正让模型动起来的是关节（Joint）上的执行器与控制器。

我举个直白的例子。你在现实里给机械臂末端换一个更重的手爪，Gazebo里对应的操作绝不是改个外观颜色，而是要修改末端link的Inertial参数，把质量加大、转动惯量调整。如果你只改了视觉模型，仿真出来的运动轨迹和受力曲线跟你实际设备完全对不上，后面做的所有算法验证都失去意义。

1.2 Classic与新版本Harmonic在模型上的差异

先交代一个背景。Gazebo目前处于新旧交替阶段，老用户熟悉的Gazebo Classic（比如Gazebo 11）与新版本的Gazebo（以前叫Ignition Gazebo，现在直接叫Gazebo，LTS版本是Harmonic）在模型格式上存在差异。

老版本的模型文件主要是SDF 1.7或更早版本，新版本已经用SDF 1.9甚至更高版本。在Harmonic里，模型加载路径、传感器标签写法、插件命名都有调整。比如老版本的<gazebo>标签下写<sensor>，新版本对传感器布局重新组织，标签层级更清晰，但如果你照着老教程抄，往往会有部分字段不生效。

还有一点容易踩坑：Harmonic默认使用的是GZ_SIM_RESOURCE_PATH而不是老版本的GAZEBO_MODEL_PATH，这个环境变量设置错了，你自定义的模型就加载不出来。后文我会专门讲这部分。

1.3 学会模型搭建与修改，能解决哪些实际问题

坦白说，纯做仿真演示，用官方自带模型库（比如Fuel模型库、机器人厂商提供的xacro描述文件）就够了。但项目一旦落到实际工程，你一定会遇到下面这些情况：

• 场景里需要一台符合你产线布局的传送带、升降机或者分拣机构，官方模型库没有现成的，就算有你也没法直接改尺寸和速度。
• 你要测试视觉算法，需要给模拟机器人加一个特定视角、特定内参的摄像头，那就得往urdf或sdf文件里加sensor块。
• 你要做的导航仿真环境与真实车间不一致，必须自己搭建匹配的测试场地，地面材质、墙体碰撞、障碍物摆放都要自己定义。
• 从GitHub上下载的机器人模型存在各种小毛病：材质路径不对、碰撞体缺失、关节限位不对，你必须手动修。

模型搭建与修改，本质上就是让仿真环境真正为你的项目服务，而不是反过来被官方demo限制了思路。这是每个做机器人仿真的人绕不开的一关。

2. 动手之前先拆解一个模型包——SDF文件到底在写什么

2.1 一个标准模型包的目录结构

不管是你自己搭的模型还是从网上下的模型，一个标准的Gazebo模型包通常长这样：

my_conveyor/ ├── model.config ├── model.sdf ├── meshes/ │ ├── conveyor_base.stl │ └── conveyor_belt.dae └── materials/ ├── scripts/ │ └── conveyor.material └── textures/ └── belt_texture.png

• model.config：模型的元信息文件，包括模型名称、作者、版本号、SDF文件路径描述。Gazebo在扫描模型目录时，先读取这个文件，才知道去加载哪个SDF。
• model.sdf：核心物理描述文件，包含模型的所有link、joint、传感器、插件定义。
• meshes/：存放外观网格文件，常见的格式有STL、DAE、glTF。注意，纯做可视化可以用这些网格，但物理碰撞和惯性计算不依赖它们。
• materials/：材质与纹理资源，影响渲染效果，不参与物理计算。

如果你是用URDF来描述机器人，那情况稍有不同——Gazebo原生跑的是SDF，ROS 2里通过spawn_entity把URDF转成SDF后加载进仿真。URDF与SDF的转换关系，我放到第六章细讲。

2.2 SDF的核心标签：model、link、joint、sensor、plugin

SDF是一种XML格式的文本文件，描述的是整个世界的物理逻辑。一个模型文件的核心结构如下：

<sdf version="1.9"> <model name="my_conveyor"> <link name="base_frame"> <pose>0 0 0 0 0 0</pose> <inertial> <mass>50.0</mass> </inertial> <collision name="base_collision"> <geometry> <box><size>2.0 0.6 0.2</size></box> </geometry> </collision> <visual name="base_visual"> <geometry> <box><size>2.0 0.6 0.2</size></box> </geometry> </visual> </link> <joint name="belt_joint" type="revolute"> <parent>base_frame</parent> <child>belt_link</child> </joint> <sensor name="camera" type="camera"> <!-- 传感器配置 --> </sensor> <plugin name="belt_controller" filename="libBeltPlugin.so"/> </model> </sdf>

这里面的关键点在于：

link表示刚体部件。每个link可以包含以下三个子标签：inertial定义质量和惯性矩阵，collision定义碰撞形状，visual定义可视化外观。这三个描述的是同一个部件的不同侧面。

joint描述link之间的运动约束关系。常见的类型有revolute（旋转关节）、prismatic（滑动关节）、fixed（固定连接）。仿真里的机器人和运动机构，全靠关节来约束自由度。

sensor和plugin是Gazebo的"传感器和执行器"层。物理引擎只负责解算运动方程，传感器数据的产生和执行器控制指令的执行，都由sensor和plugin完成。比如要让摄像头输出图像话题，就得在link上挂sensor；要让传送带以指定速度转动，就得用plugin或joint controller去控制。

2.3 URDF与SDF的关系，为什么要区分

很多做ROS的朋友对URDF更熟悉，因为机器人厂家发布的描述文件基本都是URDF。但Gazebo原生使用SDF，至少在物理引擎、传感器配置、光照设置这些层面，SDF表达得更完整、更灵活。

实际工程中，通常是这样一个流程：

1. 机器人厂家提供URDF/xacro描述文件。
2. 用xacro命令展开宏，得到完整URDF。
3. 通过ros2 run gazebo_ros spawn_entity.py传入URDF，或先转换为SDF再加载。
4. 在Gazebo中运行仿真，需要加传感器、插件时，可以直接改URDF中的<gazebo>扩展标签，或者转成SDF后在SDF中修改。

这里最常见的坑是：URDF转换SDF时，材质、颜色和mesh路径偶尔会丢失或错乱，需要手动修。网上关于Panda机械臂Gazebo仿真、UR5e机械臂搭建的教程，大量时间其实都花在修模型细节上，而不是跑通demo本身。

3. 从零搭建一个传送带模型——完整可复现的例子

3.1 为什么第一个模型建议选传送带

我见过很多新手第一个模型想搭一个工业机械臂或者AGV小车，结果被复杂的URDF、关节传动、传感器配置劝退。这里我更推荐用传送带入门，原因很实际：

• 结构简单，两个link一个joint就能表达核心运动。
• 有明确的运动关节（滑动或旋转），能直观体会到joint在SDF中的作用。
• 在产线仿真、分拣项目里特别常用，做完就能用，不会白费功夫。
• 方便后续扩展：加个相机、加个避障传感器、加个抓手，都在这个基础上改。

而且从传送带入手，你可以逐渐理解"我写的每个标签到底在物理引擎里做了什么"，而不是上来就套复杂的xacro宏，到头来只会复制粘贴不会改。

3.2 完整的传送带模型SDF代码

下面这个SDF文件是一个简化但完整的传送带模型，包含机架（base_frame）和带面（belt_link），以及一个电机简易控制插件。你可以保存为conveyor.sdf，放进自己的模型包里。

<?xml version="1.0" ?> <sdf version="1.9"> <model name="belt_conveyor"> <pose>0 0 0 0 0 0</pose> <!-- 机架：固定在地面，承担物理支撑 --> <link name="base_frame"> <pose>0 0 0.1 0 0 0</pose> <inertial> <mass>30.0</mass> <inertia> <ixx>1.2</ixx> <iyy>3.5</iyy> <izz>4.2</izz> <ixy>0</ixy> <ixz>0</ixz> <iyz>0</iyz> </inertia> </inertial> <collision name="base_collision"> <geometry> <box><size>2.0 0.6 0.2</size></box> </geometry> </collision> <visual name="base_visual"> <geometry> <box><size>2.0 0.6 0.2</size></box> </geometry> <material> <ambient>0.3 0.3 0.3 1</ambient> <diffuse>0.3 0.3 0.3 1</diffuse> </material> </visual> </link> <!-- 带面：通过滑动关节与机架连接，可水平运动 --> <link name="belt_link"> <pose>0 0 0.25 0 0 0</pose> <inertial> <mass>5.0</mass> <inertia> <ixx>0.3</ixx> <iyy>1.8</iyy> <izz>2.0</izz> <ixy>0</ixy> <ixz>0</ixz> <iyz>0</iyz> </inertia> </inertial> <collision name="belt_collision"> <geometry> <box><size>2.0 0.5 0.05</size></box> </geometry> <surface> <friction> <ode> <mu>1.0</mu> <mu2>1.0</mu2> </ode> </friction> </surface> </collision> <visual name="belt_visual"> <geometry> <box><size>2.0 0.5 0.05</size></box> </geometry> <material> <ambient>0.1 0.4 0.8 1</ambient> <diffuse>0.1 0.4 0.8 1</diffuse> </material> </visual> </link> <!-- 滑动关节：允许带面相对于机架沿x轴平移 --> <joint name="belt_slide" type="prismatic"> <pose>0 0 0 0 0 0</pose> <parent>base_frame</parent> <child>belt_link</child> <axis> <xyz>1 0 0</xyz> <limit> <lower>-1e9</lower> <upper>1e9</upper> <effort>1000</effort> <velocity>10</velocity> </limit> <dynamics> <damping>0.0</damping> <friction>0.0</friction> </dynamics> </axis> </joint> <!-- 简易速度控制插件：这里以实际插件实现为准 --> <plugin filename="libgazebo_ros_joint_state_publisher.so" name="joint_state_publisher"/> </model> </sdf>

注意上面这个SDF里，plugin只作为示例，实际工程中需要根据你安装的Gazebo版本来选择正确的插件库文件。如果是Harmonic，还需要确认插件是否兼容，最好使用官方发布的适配版本。

3.3 关键参数逐行解读，为什么要这么填

质量与惯性。很多新手觉得随便填一个质量就行，实际上仿真中的加速度、碰撞响应都直接受惯性参数影响。最简单合理的估算方法是：先根据link的尺寸和材料密度算出体积，再乘以密度得到质量。

比如机架是一个2.0 × 0.6 × 0.2 m的钢材长方体，体积是0.24 m³，乘上7850大约是1884 kg，这个明显太重了。实际机架通常是空心薄壁结构，所以我这里填30 kg，是基于"等效质量"的工程估算。仿真里的质量不需要像CAD软件那样精确建模，但要保证数量级合理。

惯性矩阵ixx、iyy、izz同样重要，它决定部件在旋转时的惯性响应。对于规则长方体，可以用公式计算：I = m * (w² + d²) / 12。上面机架质量30 kg，宽0.6 m、深0.2 m，那么绕x轴的惯性近似为30 * (0.6² + 0.2²) / 12 = 1.0，我填的1.2留有裕量，符合工程习惯。

Collision与Visual为什么分开写。Collision几何是物理引擎做碰撞检测用的，推荐尽量用基础几何体（box、cylinder、sphere）来近似，计算效率高、稳定性好。Visual几何是渲染用的，可以用更精细的mesh网格。两者的外形可以不完全重合，但关键部分必须一致，否则会出现"看起来碰到了实际没碰到"或恰恰相反的怪问题。

Joint的xyz方向。这个joint是prismatic（滑动）关节，沿世界系x轴方向（<xyz>1 0 0</xyz>）。关节方向决定了带面的运动方向。如果你打开了关节但模型不动或方向不对，第一件事就是检查这个向量。

limit中的effort和velocity定义执行器最大力和最大速度。传送带带面较轻，velocity设为10 m/s足够，effort 1000表示关节电机可以施加的最大力，过小会导致带面推不动东西。

3.4 在Gazebo中加载并验证模型

把上面的SDF保存好，启动Gazebo之后，可以用命令行直接加载：

# 启动空世界并加载模型 gz sim conveyor.sdf

如果你用的是ROS 2 + Gazebo的组合，可以通过launch文件或者ros2 run gazebo_ros spawn_entity.py来加载。模型加载进场景之后，典型验证步骤是：

1. 用鼠标点击模型，确认link外壳高亮，说明碰撞体加载成功。
2. 尝试拖动带面，看它是否能沿着x轴平移，确认joint方向正确。
3. 查看主题列表，确认插件发布的话题出现。例如joint state publisher正常的话，应该能看到/joint_states话题。

如果你发现模型加载后直接掉到地面下面，或者方向不对，大概率是<pose>设置或者collision缺失导致，排查方向就明确了。

4. 改模型才是日常——6个高频修改需求与操作路径

4.1 换个颜色、换个尺寸，注意Collision必须同步

修改外观和尺寸是入门操作，但也最容易出问题。比如把传送带的带面长度从2米改成3米，很多人只改了visual里的<box><size>，结果模型看起来变长了，但物理碰撞还是原来的2米。这就像你穿了一件明显不合身的衣服——视觉上变了，身体接触感受没变。

正确的修改方式：

<!-- 带面 visual --> <visual name="belt_visual"> <geometry> <box><size>3.0 0.5 0.05</size></box> </geometry> </visual> <!-- 带面 collision 同步修改 --> <collision name="belt_collision"> <geometry> <box><size>3.0 0.5 0.05</size></box> </geometry> </collision>

尺寸修改有个技巧：先改collision再改visual。原因很简单——碰撞体是物理仿真的核心，先把它调到位，再改视觉外观去匹配，能避免很多"看起来正常但物理行为异常"的困扰。

颜色方面，应用<material>里的ambient和diffuse即可，主流RGB模型下，三通道值在0到1之间。如果想用纹理图片，把纹理文件放到materials/textures/下，在material里引<texture>标签，路径相对于model包根目录。

4.2 给机械臂加一个摄像头，图像话题怎么出来

加传感器是模型修改里最常见也最有价值的需求。比如给机械臂末端加一个用于二维码检测的摄像头，你可以直接在对应的link下加sensor块：

<sensor name="hand_camera" type="camera"> <pose>0.05 0 0.1 0 0 0</pose> <camera> <image> <width>640</width> <height>480</height> </image> <clip> <near>0.05</near> <far>100</far> </clip> <horizontal_fov>1.05</horizontal_fov> </camera> <always_on>1</always_on> <update_rate>30</update_rate> </sensor>

关键在于几个参数：update_rate表示图像刷新频率，视觉检测一般30 Hz够用，太高会增加仿真负载；horizontal_fov是水平视场角，单位是弧度，1.05 rad大约等于60度，如果需要更广视野可以调大到1.57（约90度）。

配合ROS 2使用时，还需要在URDF的<gazebo>扩展标签里指定ROS 2的相机插件：

<gazebo reference="hand_camera_link"> <sensor type="camera" name="hand_camera"> <plugin filename="libgazebo_ros_camera.so" name="camera_plugin"> <ros> <namespace>hand_camera</namespace> <remapping>image_raw:=image_raw</remapping> </ros> <camera_name>hand_camera</camera_name> <image_topic_name>image_raw</image_topic_name> <camera_info_topic_name>camera_info</camera_info_topic_name> <frame_name>hand_camera_link</frame_name> </plugin> </sensor> </gazebo>

我自己实测时踩过最大的坑是：相机加上了，但图像话题一直黑屏。排查了一圈，最后发现是渲染层面没走GPU导致图像无法输出。这个问题我在第五章详细展开。

4.3 加关节与改运动范围，别把limit参数当摆设

关节是模型实现运动的中枢。你要给机械臂增加一个旋转关节，或者修改现有关节的运动范围，需要关注的是<limit>里的四个值：

一个很典型的工程问题：机械臂模型在Gazebo里"塌"下来了。很多人以为是自己把模型的某个link拆坏了，实际上是关节的effort设置过小，关节电机输出力矩无法支撑重力矩，于是机械臂在重力的作用下自然下垂。这就好比你用一个扭矩不够的电机去驱动一个很重的手臂，它当然撑不起来。解决方式就是适当增大effort值。

修改关节运动范围时，还有一个细节容易漏：joint的<axis><xyz>方向与上下限的正负对应。如果你的关节角度是从某个初始姿态开始测量的，xyz方向定义了指正方向，每次修改前先确认这个方向，不然改完的限位可能和你期望的完全相反。

4.4 外部模型文件怎么改：mesh路径、单位、材质经典三大坑

从网上下载的模型包，或者从SolidWorks等CAD软件导出的模型，改起来往往比从零写的还麻烦。最常见的三大坑：

Mesh路径不对。模型文件里引用的.dae或.STL路径是相对路径，如果你的模型包目录层次与原作者不同，Gazebo就找不到网格文件，模型会显示成一片空白或者加载失败。解决办法是打开SDF确认路径，并保证mesh文件在对应位置。如果是URDF，路径可以用package://前缀，但SDF里通常用相对路径或绝对路径。

单位问题。STL文件没有单位约定，不同软件导出的可能是毫米、可能是米。一个典型的场景：你在SolidWorks里建模时用的是毫米，导出STL后尺寸数值是几千，但Gazebo默认按米解释，模型就变成了一座巨山。检查模型尺寸的方法是：在Gazebo里用滚轮缩放看模型占场地的大小，或者直接读SDF里mesh的size信息。修改SDF中 标签的数值，可以快速做单位换算。毫米转米，scale三个方向填0.001 0.001 0.001即可。

材质丢失。DAE文件自带材质定义，但路径如果指向本地绝对路径，换台电脑就失效。最稳妥的做法是统一改到模型包内的materials/textures/下，并在SDF的material标签中手动指定<ambient>、<diffuse>作为降级方案，这样即使纹理加载失败，模型也不会变成纯白。

4.5 修改后模型不生效？一套排查清单

模型改了但没效果，是每个做Gazebo的人都会遇到的日常。根据我的经验，按以下顺序排查，大部分问题都能解决：

1. 缓存问题：Gazebo默认会缓存模型信息，尤其是模型名称、sdf路径。你修改了SDF内容但仿真里加载的还是旧模型，先试着重启gz sim进程并清理~/.gz或/tmp下的缓存目录。
2. SDF版本：确认SDF的<sdf version="...">与你安装的Gazebo版本兼容。Harmonic主推1.9以上，Classic 11支持1.7。版本不匹配时，有时报错很明显，有时只是某些标签被静默忽略。
3. 模型名冲突：两个模型包如果使用了相同的<model name>，Gazebo可能只加载先扫描到的那个，或者干脆报错。给你的模型起唯一性名称，这是最容易被忽略的坑。
4. 环境变量：确认GZ_SIM_RESOURCE_PATH已经包含你的模型包目录。Harmonic下如果你忘了设置这个变量，无论如何也加载不出来自定义模型。
5. XML语法：SDF是严格的XML格式，标签没有闭合、属性值没有引号都会导致解析失败。推荐用支持XML校验的编辑器（VS Code装XML插件），保存前先格式化校验一遍。

5. 别忽视的性能与真实感：GPU加速、物理参数与大型场景优化

5.1 GPU加速不是开了就有效，你得会验证

很多人在Gazebo里场景稍微复杂点，帧率就掉到个位数，第一反应是电脑性能不行。实际上，大部分情况下问题出在渲染后端没走GPU。

Harmonic默认使用的是OGRE 2渲染引擎，这是新一代Gazebo在渲染画质上的巨大提升，但前提是正确启用了GPU渲染。常见做法是设置环境变量：

export IGN_RENDERER=ogre2

有些环境还需要指定GPU设备和渲染回退策略。设置完之后，怎么确认GPU真的在干活？一个简单有效的办法：打开系统资源监视器，观察加载复杂场景时GPU占用率是否明显上升。如果GPU占用率纹丝不动、CPU占用率却飙升，说明渲染还是走了软件模式，需要检查你的显卡驱动和OGRE 2的配置。

对于Classic老版本，对应的渲染引擎是OGRE 1，也可以用export GAZEBO_RENDER_ENGINE=ogre之类的方式调整。但新项目我建议直接上Harmonic，画质和性能上限都高一个档次。

5.2 物理引擎参数：step size和real_time_factor决定仿真质量

模型搭建好了，传感器和插件都配好了，但如果物理参数没调对，仿真的数据和真实世界对不上，后面做的所有算法验证都会失真。

Gazebo的物理引擎配置通常在World文件（或默认参数）里定义：

<physics type="ode"> <max_step_size>0.001</max_step_size> <real_time_factor>1.0</real_time_factor> <real_time_update_rate>1000</real_time_update_rate> </physics>

• max_step_size：物理仿真步长，单位秒。步长越小，仿真精度越高，但计算量越大。0.001秒是常见选择，移动机器人用0.005也能接受，机械臂高动态场景建议0.001。
• real_time_factor：实时因子，1.0表示仿真速度与真实时间一致。如果你只是想快速跑数据，可以把这个值调大（比如2.0甚至5.0），但要注意步长和实时更新率的匹配。
• real_time_update_rate：每秒物理更新的次数，通常等于1 / max_step_size。

一个我反复遇到的教训：当仿真实时性无法满足时，模型会出现"飘"或者穿模现象。比如传送带上的工件陷入带面、机械臂末端抖动。这个问题的根源不是模型搭建错误，而是物理引擎计算负荷过高，一直追赶不上真实时间。这时候强行要求实时因子1.0没有意义，要么降低max_step_size，要么优化场景复杂度。

5.3 大型场景和复杂模型的优化思路

当你的仿真环境里模型数量多、mesh面数高、传感器数量大时，性能会明显下降。我的优化经验按优先级排序如下：

1. 简化碰撞模型：把传感器只用于渲染的精细mesh排除在碰撞检测之外。记住：碰撞几何越简单，物理引擎越快。很多物体的碰撞体用一个box或cylinder近似就完全够用。
2. 减少mesh三角面数：复杂的DAE网格文件常常有几万甚至几十万个三角面。用MeshLab等工具做减面处理，保留外观关键特征的前提下把面数降到几千，渲染性能提升非常显著。
3. 控制传感器数量和更新频率：每个开启的sensor都在消耗CPU。定位用的激光雷达可以10 Hz，视觉检测用的相机30 Hz够了；对精度要求不高的传感器，降低更新率能省大量计算资源。
4. 尽量复用静态模型：把场景里不动的物体合并成一张大的静态模型，或者直接用模型库里的静态物体，避免大量独立link参与物理解算。

有一回我在做产线仿真时，场景里放了30多个工装夹具模型，都是从CAD导出的高精度mesh。Gazebo直接卡成PPT。后来我把所有夹具的collision统一换成box，visual mesh做减面，性能立刻恢复到了实时。

6. Gazebo与ROS 2联调时的模型问题与进阶方向

6.1 从URDF到Gazebo：加载模型和跑通SLAM的完整路径

做完模型搭建和修改，下一步自然就是联调ROS 2。毕竟在Gazebo里建模型只是手段，让机器人跑起来、让算法跑起来才是目的。

从URDF到Gazebo仿真的标准流程是三步走：

第一步，准备机器人描述包。大多数开源机器人（比如UR5e、Panda）都有现成的URDF或xacro描述文件。xacro宏需要先展开：

ros2 launch ur_description ur5e.launch.py

如果有URDF/xacro文件，也可以手动展开：

xacro ur5e.urdf.xacro > ur5e.urdf

第二步，启动Gazebo世界，然后把机器人模型加载进去。ROS 2生态里最常用的方式是：

ros2 launch gazebo_ros gazebo.launch.py world:=path/to/your_world.sdf ros2 run gazebo_ros spawn_entity.py -topic /robot_description -entity ur5e

有的launch文件里结合了spawn_entity.py，实现在启动世界后自动加载机器人。

第三步，给机器人添加Gazebo控制器和传感器插件。这一步最容易出问题：URDF文件里的<gazebo>扩展标签写了控制器插件之后，需要在机器人状态发布器、控制器管理器里同步配置，否则模型在Gazebo里虽然能看见，但是关节不受控制。

做完这三步，你就可以测试SLAM、导航或者机械臂运动规划了。很多朋友问"ROS 2 Gazebo SLAM怎么跑通"，本质就是把这几步链路打通，再启动SLAM工具链。

6.2 联调阶段最常踩的模型相关坑

联调阶段的报错，一半以上都跟模型相关。我整理几个高频问题：

问题一：话题对不上。Gazebo里的传感器话题命名与你的算法节点订阅的话题不一致，最常见的原因是命名空间（namespace）没理清。检查/ros__parameters里的frame_name、topic_name，确保与实际发布的话题一致。推荐用ros2 topic list实际看看Gazebo发布了什么，而不是对着配置文件猜。

问题二：TF树断链。URDF里定义的link层级不完整，或者有的link没有在Gazebo中正确生成TF，导致你的可视化工具和算法系统找不到机器人模型之间的变换关系。这种情况一般需要检查URDF中每个link是否都加了<inertial>，以及Gazebo是否成功发布了/tf。

问题三：机器人从地面掉落或者乱飞。这是最灾难性的表现，通常原因有三：模型缺少collision定义，机器人没有任何碰撞几何，直接从地面穿过；inertial参数严重异常（比如质量填了0），物理引擎无法稳定解算；或者关节的effort设置过小，无法支撑机器人自重。排查时先把物理参数调保守，关闭自碰撞（self_collide）看看是否恢复正常。

问题四：图像话题黑屏。传感器topic存在但图像全黑，基本可以确定是渲染问题。先确认GPU加速是否生效，再检查相机pose是否被墙体遮挡，最后检查near/far裁剪面是否过于极端。二维码检测用的相机，我建议把near调小一点（0.01或0.05），否则太近的二维码会完全不可见。

6.3 进阶方向：嵌套模型、参数化、插件开发

当你掌握了基础搭建和修改，可以考虑以下几个进阶方向，让你的模型能力上一个台阶：

嵌套模型（Nested Model）。Gazebo支持在SDF中通过<include>引用其他模型，形成嵌套结构。比如你做一个AGV底盘模型，可以直接include一个现成的激光雷达模型，而不必重新写一遍雷达传感器配置。这在大型项目里可以极大提高模型复用效率。

参数化模型（xacro宏）。URDF的xacro宏机制非常适合做参数化设计。你定义一个传送带宏，把长度、宽度、速度作为参数，然后同一套代码生成不同规格的传送带。Gazebo的SDF虽然本身不直接支持宏，但你完全可以先用xacro生成SDF再加载，这样既享受了参数化的便利，又不丢失SDF的表达力。

自定义插件开发。Gazebo的插件系统允许你写C++代码扩展仿真能力。比如给传送带写一个速度控制器插件、给视觉传感器写一个二维码识别插件。这在做虚实结合项目时非常有用——真实系统用什么协议控制设备，仿真里就可以用同一个协议去控制虚拟设备。

在线模型库与官方包获取。Gazebo官方有Fuel模型库，里面有很多社区贡献的高质量机器人模型和场景模型。在ROS 2环境下，很多官方示例包（比如gazebo_ros_pkgs）可以通过apt直接安装，也可以在源码编译时同步获取，里面自带的演示模型是学习模型配置的绝佳素材。

另外提一句，如果你想快速体验在线仿真环境，有部分云平台提供了浏览器内运行的Gazebo，不用配环境就能上手操作，适合刚接触的人先熟悉交互和流程。但真做项目，我还是建议本地把环境搭利索。

6.4 改动模型前的一个好习惯：diff对比

最后分享一个我个人的工作习惯。改模型文件之前，无论改动多么小，先复制一份原始文件，用版本管理工具记录修改痕迹。用Git维护模型包是个好主意。每次改动后，用git diff查看改动内容，确认自己只改到了预期标签，没有误伤其他地方。

有一次我为了调整机械臂的关节限位，连续改了一下午，到晚上发现机械臂行为越来越奇怪。后来用git diff一查，才发现早前修改某个link尺寸时，不小心把同文件里另一个link的collision size也改了。如果没有版本记录，这种问题定位起来极其痛苦。

模型修改和代码开发一样，是个需要细致和重复试错的过程。尽量用最小改动验证一个功能，改一点、测一点，别一次性改一大堆再找问题，那个排错成本太高了。

玩Gazebo几年下来，我的体会是：模型文件其实就是你和仿真世界沟通的语言。刚开始会觉得很繁琐，各个标签、参数让人眼花缭乱，但当你亲手从零搭出一个能用的产线场景，看着机械臂在传送带旁边稳定抓取时，那种掌控感是直接用现成demo完全体会不到的。希望这篇文章能帮你少走一些弯路，更快地到达那个"看见物理引擎"的阶段。