企业官网建设流程全解析

做 Gazebo 仿真最尴尬的时刻，不是你编译不通过，而是你满怀期待打开一个空旷的 world，结果里面只有一块灰扑扑的地面，想让机器人跑个避障、让无人机找个山谷穿越都没有可用的参考点。很多做机器人的朋友都有过这种体验：默认的 empty.world 和 demo world 只适合验证节点通不通，根本没法承载带任务逻辑的仿真测试。所以 Gazebo 仿真环境做到一定阶段，自定义世界是绕不过去的一步。

这篇文章是 Gazebo 仿真环境系列教程的第四篇，重点讨论如何在 Gazebo 中创建自定义世界。我会从 .world 文件的结构讲起，逐步覆盖地面、物理参数、光照、地形、模型放置，以及怎么把做好的 world 接到 ROS2 和飞控仿真里去。适合已经能熟练打开 Gazebo、能控制机器人移动，但还想复现自己场地或者测试场景的开发者。

1. 自定义世界的底层逻辑：.world 文件、SDF 语法和模型加载路径

1.1 world 文件到底是一份什么样的文档

很多人最开始接触 Gazebo 时，只知道gazebo命令会打开一个默认环境，后来看到gazebo --world my.world才意识到：原来世界也是可以指定文件加载的。但真正上手去写一个 .world 文件时，第一反应往往是去网上找别人的代码，复制过来改两下，发现跑不起来，然后又回到默认环境用了。

我觉得这里最大的拦路虎不是语法本身，而是大家没有理解“自定义世界”在 Gazebo 里定义的是哪一个层级。Gazebo 使用 SDF 格式来描述整个世界，后缀一般是.world或.sdf。一个完整的世界文件，本质上是把一个<world>标签下的所有内容描述清楚，包括但不限于：

• 全局物理参数：重力、步长、迭代次数、摩擦模型；
• 场景视觉参数：光照颜色、背景颜色、阴影、天空盒；
• 静态模型：地面、建筑、道路、墙、树、路标；
• 动态模型：可能作为任务目标的物体、需要抓取的箱子等；
• 传感器模型与插件：这些通常会放在机器人模型里，但也可以独立放置在世界中。

所以你可以把 .world 文件理解成“仿真场景的入场券”。里面写的每一个模型、变量和链接关系，都会决定仿真开始时系统的初始状态。这和真实世界不一样，真实世界你不能说“这一块重力小一点”，但仿真里你可以，特别是做多机测试、算法极端工况测试时，这个能力非常值钱。

1.2 版本差异：Gazebo Classic 与 SDF 版本的匹配关系

要自定义世界，绕不开版本问题。Gazebo 的版本迭代导致 SDF 版本也在变，网上很多教程还是老的 sdformat 1.4 语法，放到新版本上可能能解析，但有些标签已经失效或者弃用。我的建议是，先跑一下gazebo --version确认当前用的是哪个版本。

比如 Ubuntu 22.04 上很多人的 ROS2 环境用的还是 Gazebo Classic 11，那么对应的 SDF 版本通常是 1.7。如果你在系统里装了 Gazebo 11，并且写的是：

<?xml version="1.0"?> <sdf version="1.7">

大部分情况下没问题。如果你是跟着较新的教程用了 Ignition Gazebo 或 Gazebo Sim，SDF 格式里少了<world>标签的某些旧字段，而多了<scene>子标签的新的写法。虽然 Gazebo 的 SDF 解析器有很强的容错能力，但如果文件写错，报错信息很晦涩，经常只提示一个行号，你得人工排查半天。

我在实际开发时常用的做法是，先用 Gazebo 自带的模型库做一个模板文件，然后一点一点加内容。这样能保证 SDF 版本和当前 Gazebo 解析版本匹配，减少从零造轮子的时间。

1.3 模型加载路径：model://、file:// 和 GAZEBO_MODEL_PATH

当你开始自定义世界后，很快会遇到第二个困惑：为什么一个模型我明明放在了某个目录下，加载 world 时却仍然提示找不到。这就要说到模型加载路径问题。

Gazebo 识别模型的方式不是把模型文件一股脑塞进 world 文件里，而是使用类似 URL 的写法。比如说：

<include> <uri>model://my_robot</uri> <name>robot1</name> <pose>0 0 0.2 0 0 0</pose> </include>

这里的model://my_robot不是相对路径，它依赖环境变量GAZEBO_MODEL_PATH。如果你没设置这个环境变量，Gazebo 完全不知道my_robot在哪里。这种情况在刚接触自定义世界的人身上发生频率特别高，包括我自己也踩过这个坑：明明模型文件夹就在旁边，但是不 export 路径，它就是加载不出来。

解决方式很简单，在.bashrc里加上：

export GAZEBO_MODEL_PATH=$HOME/gazebo_models:${GAZEBO_MODEL_PATH}

然后重新打开终端，再启动 Gazebo。如果你只是临时测试，也可以在当前终端里先 export 再启动。

理解这一点对自定义世界非常重要，因为你在 world 文件中写的所有model://引用，本质上都是告诉 Gazebo “我要使用这个模型”，而至于模型的内容、外观和物理属性，则应该放在独立的模型目录中，由模型描述文件来定义。这样设计的好处是，一个模型可以被多个 world 文件复用，避免每个 world 里都复制一大段重复代码。

2. 手写第一份世界文件：物理、场景与光照参数的正确打开方式

2.1 最小可运行的自定义 world 长什么样

许多教程会直接让你用 Gazebo 自带的图形界面建模，然后保存成 .world 文件。这种模式确实可以，尤其是 Gazebo 中的 Building Editor 可以比较快地搭出墙体和房间结构。但如果你做的是室外场景、多传感器融合或者特殊物理仿真，图形界面有时会很痛苦。

我建议至少能手写一个最小 world 文件出来。下面这个文件是一个很实用的起点：

<?xml version="1.0"?> <sdf version="1.7"> <world name="custom_world"> <physics type="ode"> <max_step_size>0.001</max_step_size> <real_time_factor>1</real_time_factor> <real_time_update_rate>1000</real_time_update_rate> <gravity>0 0 -9.80665</gravity> </physics> <scene> <ambient>0.6 0.6 0.6 1</ambient> <background>0.3 0.4 0.6 1</background> <shadows>true</shadows> <fog> <type>linear</type> <color>0.7 0.7 0.7 1</color> <start>30</start> <end>80</end> </fog> </scene> <include> <uri>model://sun</uri> </include> <include> <uri>model://ground_plane</uri> </include> </world> </sdf>

这已经是一个可以加载的自定义世界了：地面上有光照、有阴影、有雾，物理引擎使用 ODE，重力方向朝下，仿真时间与真实时间同步。保存为my_world.world，然后运行：

gazebo --verbose my_world.world

如果你能看到地面和太阳，说明整个文件结构没有问题，后续往里面加地形、加模型就有基础了。

2.2 为什么物理参数不能直接抄默认值

很多人在写世界文件时习惯于把 physics 标签完全复制自官方自带的例子。实际上这可能会影响你后面的算法测试。这里有几个参数在实际使用时需要认真思考：

real_time_factor表示仿真时间与真实时间的比例。如果设置为 1，那么仿真中的 1 秒就是真实世界的 1 秒。如果你在做无人机仿真，PID 参数调试对时间敏感，这个值不宜设得太高。如果你只是想快速验证某个长时任务，可以把real_time_factor调大，让仿真跑得比真实时间快，但这样会影响传感器数据的真实感。

max_step_size直接影响物理引擎的精度和稳定性。默认的 0.001 在大多数情况下是安全的，但如果你的世界包含大量高摩擦接触，或者机器人运动速度非常快，步长过大容易出现物体穿透。反正我个人的经验是：当你在 Gazebo 里看到机器人莫名其妙穿地，先不要怪模型，检查一下步长和碰撞参数。

还有重力。说句玩笑话，在 Gazebo 里改重力方向是我最喜欢拿来验证机器人是否真正常流程的测试。比如做月球车场景，就把重力改成 1.62 m/s²，此时轮子的驱动力裕量完全不同。这些参数在真实世界无法自由调整，但在仿真是可以低成本修改的。

2.3 光照和场景参数不能只图“好看”，它会影响传感器数据

很多初学者对<scene>标签不上心，觉得只是视觉美观问题。但如果你后面接了激光雷达或视觉传感器，光照和场景参数对仿真数据的影响就非常直接。

举个例子，激光雷达是通过射线与物体的碰撞来获取距离的。你如果把<ambient>调得很暗，视觉相机模块拍出来的画面会偏暗，这会影响目标检测调试。你如果把雾开得太大，激光点云虽然通常不受雾的影响，但相机图像会严重退化，这在某些测试中是你想要的，但在另外一些场合却是干扰。

所以写自定义世界时，我不会一上来就搞花里胡哨的纹理。先确定这个场景的主要用途：是室内 SLAM，还是室外越野？是视觉为主，还是激光为主？根据用途再来决定光照策略。比如做二维激光雷达测试时，墙体和障碍物的反光能力强弱并不重要，因为识别靠的是距离；但做视觉检测，场景纹理、光照均匀度就变得很重要。

2.4 地面模型用什么取决于你需要的摩擦系数

自定义世界的地面不一定都要使用ground_plane。ground_plane本身是一个很简单的无限平面模型，它适合做快速验证，但不适合做复杂的滚动力学分析，因为它的高度固定为 0，如果你想做一个带坡度的地面，这个模型就没法满足。

如果你想做一个自定义的道路或坡道，推荐的做法是创建一个新模型，然后在模型里定义一个 link，给该 link 添加碰撞体和视觉体。最简单的坡道可以这样写：

<model name="ramp"> <static>true</static> <link name="link"> <visual name="vis"> <geometry> <box> <size>2 1 0.2</size> </box> </geometry> </visual> <collision name="col"> <geometry> <box> <size>2 1 0.2</size> </box> </geometry> <surface> <friction> <ode> <mu>1.0</mu> <mu2>1.0</mu2> </ode> </friction> </surface> </collision> </link> </model>

这里的<static>true</static>很关键。静态模型不会受到重力影响而塌陷，也不会被机器人推走。如果你只用<pose>里设置了一个旋转角度来表现坡道，但忘了设置 static，那么仿真一开始，坡道可能会在地面上滑动甚至弹跳。我见过太多这种“起飞的地面”了，原因就是静态属性没设对。

3. 给地形敷上真实感：高度图、三维网格模型和碰撞体的设置细节

3.1 为什么无人车和无人机仿真需要自定义地形

写完了平坦的基础 world 之后，很快你会遇到一个新的需求：测试环境不是一块平地怎么办？

无人机要测试避障，需要山谷、斜坡或建筑物；无人车要做越野，需要起伏路面、泥土区域和草地。对比 Gazebo 默认的 ground plane，自定义地形带来的仿真难度是质变级别的。

Gazebo 支持两种主要的地形表达方式：一是使用高度图 Ground Heightmap，二是加载外部三维模型（如 DAE、STL、OBJ 格式）。两者各有适用场景，不要一上来就做 OBJ 网格模型，因为网格模型里有时会包含大量顶点，导致 Gazebo 启动时加载慢，而且碰撞体计算开销大，仿真实时性会明显下降。

高度图在简单地形模拟上有明显优势。你只需要准备一张灰度图，每个像素代表一个高度值，Gazebo 会把这个二维图像插值成三维地形。这样既能表现山脉、土坡、坑洼，又不至于像导入大量网格那样消耗太多性能。

3.2 在 world 中直接引用 heightmap 模型

让我直接给一个高度图模型的示例。首先准备一张灰度 PNG，放在你的模型目录下，结构可以是这样：

gazebo_models/ my_terrain/ model.config model.sdf materials/ heights/ terrain.png textures/ grass.png

然后 model.sdf 中只定义一个 link，但 link 的 visual 和 collision 都要使用<heightmap>：

<?xml version="1.0"?> <sdf version="1.7"> <model name="my_terrain"> <static>true</static> <link name="base"> <visual name="visual"> <pose>0 0 0 0 0 0</pose> <geometry> <heightmap> <uri>model://my_terrain/materials/heights/terrain.png</uri> <size>100 100 10</size> <pos>0 0 -5</pos> <texture> <diffuse>model://my_terrain/materials/textures/grass.png</diffuse> <normal>model://my_terrain/materials/textures/grass.png</normal> <size>1</size> </texture> </heightmap> </geometry> <material> <ambient>0.8 0.8 0.8 1</ambient> <diffuse>0.8 0.8 0.8 1</diffuse> </material> </visual> <collision name="collision"> <pose>0 0 0 0 0 0</pose> <geometry> <heightmap> <uri>model://my_terrain/materials/heights/terrain.png</uri> <size>100 100 10</size> <pos>0 0 -5</pos> </heightmap> </geometry> <surface> <friction> <ode> <mu>1.2</mu> <mu2>1.2</mu2> </ode> </friction> </surface> </collision> </link> </model> </sdf>

模型里的几个参数需要注意一下。<size>是高度图在地图坐标系中的实际大小。这里100 100 10表示地形在 X、Y 方向各 100 米，高度范围是 10 米。<pos>则是地形的中心位置偏移量。由于高度图默认以图像左上角为原点，而且 Z 轴是基于图像亮度值生成，所以如果你不把 pos 设成负值，很容易出现一块高度中心抬升、机器人进入后直接踩空的情况。

高度图的准备方法有很多，你可以直接用图像处理软件把一张灰度图翻转、模糊，也可以在 GIS 工具里把 DEM 数据导出为 PNG。但要注意，RGB 值到高度并不是线性对应，Gazebo 读取的高度值是基于像素强度映射到 0~size.z 的范围。像素越亮代表高度越高，越暗代表越低。最深处不一定是 0，需要自己去校准。

3.3 地形模型的常见坑：只做视觉不做碰撞、坐标对不齐

第一类坑是视觉和碰撞几何不一致。很多人导出三维地形网格后，为了省性能，只把精细网格用在了 visual 上，collision 则用了一个粗糙的大 box。这样跑起车来时视觉上明明已经骑上了土堆，但物理反馈完全不对，轮子可能直接穿过地面。需要排查时，又非常难找到问题的源头，所以我的原则是：地形场景里，visual 和 collision 至少要有一层对应的区域覆盖。如果精细模型性能不够，可以退一步用更粗的高度图，也不能让视觉和碰撞差太远。

第二类坑是坐标对不齐。高度图模型的<pos>和模型的<pose>是两个不同的坐标参数，很多人分不清楚。模型的 pose 是模型在整个世界坐标系中的位置。而 heightmap 的 pos 是高度图相对模型 link 的位置。如果你不想额外做坐标换算，最好在模型的 link 里用0 0 0，然后在 world 文件的 include 里写 pose。这样维护起来直观得多。

3.4 如果坚持使用外部三维网格模型，需要注意什么

如果你需要非常精确的建筑物地形，比如做一个室内楼层、或者某个工业现场的扫描模型，那高度图可能不够，需要使用外部网格。这时候最推荐的格式是 STL 或 DAE。STL 适合做纯碰撞体，因为它没有颜色材质；DAE 可以带上纹理，适合做视觉体。

Gazebo 的接口比较直接：

<geometry> <mesh> <uri>model://my_environment/meshes/building.dae</uri> <scale>1 1 1</scale> </mesh> </geometry>

但要把外部模型文件本身做成一个模型目录，不要直接把它硬塞进 world 文件正文。很多人在第一次导入这样 mesh 的时候会图省事把 .dae 放在任意路径，结果 world 文件里只能写绝对路径，下次换一台电脑就挂。这在本机开发时没有感觉，但放到团队里或者换环境后特别痛苦。标准做法仍然是把 mesh 做成 model 目录，并通过 GAZEBO_MODEL_PATH 来引用。这也是我想提醒大家的：自定义世界不只是写一个 .world，还要维护好配套的模型库。

4. 世界里放模型：模型目录结构、静态属性与碰撞体的关系

4.1 从 model:// 出发，把所有模型组织成统一目录结构

如果你在 world 中只是使用 Gazebo 默认模型库里的物体，比如model://sun、model://ground_plane，那不需要自己建模型目录。但当你开始增加自定义建筑、障碍物、目标点区域标识时，就需要一套清晰的模型组织规范。

下面是一个推荐的目录结构：

gazebo_models/ my_building/ model.config model.sdf my_wall/ model.config model.sdf materials/ textures/ wall.png

model.config是模型元数据的文件，里面至少要有下面这些内容：

<?xml version="1.0"?> <model> <name>my_building</name> <version>1.0</version> <sdf version="1.7">model.sdf</sdf> <author> <name>Your Name</name> </author> <description>自定义测试建筑</description> </model>

模型的名字my_building和目录名my_building不一定完全一样，但我们团队的习惯是保持一致，省得后续解析时产生混乱。

在 model.sdf 中再去定义 link、collision、visual 等内容。这样一个模型可以被多个世界文件复用，也可以在终端单独用spawn_model或者spawn_entity把模型动态放进去。

4.2 模型中 static 和 dynamic 的区别，决定了它是障碍还是交互物

你可以在 world 的<include>里直接给某个模型加入额外的 pose。例如：

<include> <uri>model://my_wall</uri> <name>wall_01</name> <pose>10 5 0 0 0 0.5</pose> </include>

但真正决定这个模型是被机器人撞飞，还是像一堵墙那样纹丝不动的，是模型自身 SDF 文件里的<static>属性。

一个<static>true</static>模型，不会参与物理动力学计算，只会保留碰撞体的几何信息。所以机器人撞上去会感受到碰撞响应，但墙不会受伤、不会移动。如果你做的是抓取物体任务，物体应当是<static>false</static>，并且要有合适惯量，否则抓取力和接触力的表现会很怪。

这里还有一个很多新手不知道的细节：静态模型没有速度，也没有加速度，很多算法里的“速度观测”对它没有意义。因此当你做自主导航的代价地图时，静态障碍物和动态障碍物会走完全不同的处理路径。如果世界文件把所有模型都设为静态，那么机器人的动态避障就需要完全依赖传感器实时感知，否则它随时可能撞上后来出现在视野里的物体。

4.3 碰撞体参数的调参经验：mu、摩擦、碰撞矩阵

Gazebo 的碰撞体碰撞参数里，除了常见的<mu>和<mu2>，还有<kp><kd>等软接触参数。对大多数场景来说，设置 mu 表示滑动摩擦系数就够了。mu 和 mu2 分别代表两个正交方向上的摩擦系数，如果你设置的是各向同性材料，那么 mu 和 mu2 保持相同即可。

我踩过的坑是，在自定义世界里放置一个非常轻的物体，给它设置 mu 很大后发现物体经常打滑，怎么调速度控制器都不对。后来才发现不是物体重量的问题，而是物体模型的质量太小，导致接触力不足以产生足够的摩擦力来抵抗轮子的驱动力。在真实世界中，一个 1 kg 的小方块在湿滑地面上会有完全不同的行为，仿真里也一样，物理参数是互相耦合的，不能只调一个摩擦系数就指望机器人不滑。

4.4 编辑器和手写结合：Building Editor 适合室内墙体的快搭

Gazebo Classic 自带 Building Editor，适合快速搭室内房间、围墙、走廊等规则结构。它导出的模型仍是一个构件模型，你之后可以去改 model.sdf。不过它的缺点也很明显：导出的墙体和地面通常都是静态模型，而且命名比较乱，后期如果要基于这些墙体生成导航地图，需要额外对齐。

我的建议是：规则房间用 Building Editor 起步，再手工改导出文件的坐标命名；不规则地形和高度图则不要依赖编辑器，直接手写 SDF 更高效。

5. 把自定义世界接到 ROS2 和仿真控制端：launch 文件与生成点设置

5.1 通过 gazebo_ros 启动自定义 world

如果你是在 ROS2 环境里做机器人开发，那么你不仅是想要一个能看的 Gazebo world，还希望这个 world 和 ROS2 的节点体系打通。常见的做法是用gazebo_ros包提供的共享库来启动 Gazebo，这样 Gazebo 启动后就有对应的 ROS 接口。

一个典型的 launch 文件大致是：

from launch import LaunchDescription from launch.actions import ExecuteProcess from launch_ros.actions import Node def generate_launch_description(): world_file = '/home/user/gazebo_worlds/my_world.world' return LaunchDescription([ ExecuteProcess( cmd=['gazebo', '--verbose', world_file, '-s', 'libgazebo_ros_init.so'], output='screen' ), Node( package='gazebo_ros', executable='spawn_entity.py', arguments=['-entity', 'my_robot', '-database', 'my_robot', '-x', '0.0', '-y', '0.0', '-z', '0.5'], output='screen' ) ])

这里的-s libgazebo_ros_init.so参数会自动加载 gazebo_ros 的初始化插件，让 ROS 节点能跟 Gazebo 通信。如果你是手动打开 Gazebo 界面，那么需要在“插入”模型或者其他界面操作中单独选择加载，启动脚本反而更稳定。

第二个节点 spawn_entity 会把机器人模型加载到 Gazebo 世界中的指定位置。这个方法比每次手动点击 GUI 插入模型更适合测试，因为坐标和姿态可以由脚本控制，方便做自动化批量测试。

5.2 生成点不一定要在原点：坐标系从哪里来

自定义世界里，机器人初始坐标如何确定，这是个容易出错的问题。Gazebo 里一个 model 的 pose 是相对于世界上层的 parent link，而 world 顶层默认的坐标系就是世界坐标系。因此你填的-x 0 -y 0是相对于世界原点的位置。

如果你在 world 中放置了ground_plane，地面平面其实并不是一个会影响机器人坐标的父级，它只是个无限大的碰撞体。也就是说，机器人坐标系和地面平面之间没有父子关系，地面只是为机器人提供支持力。这个特点与真实世界完全一致，但很多做惯了三维软件的人会下意识觉得，如果机器人放在地面上，机器的 pose 应该相对于地面模型来设置。

在自定义世界里，建议先在草地上画一个可视化的“出生圈”，比如铺一个半径 1 米的扁圆柱，这样你在 launch 文件里设置的坐标离目标点远近一眼就能看出来，省得反复调试。

5.3 ROS2 节点与 Gazebo 之间时序问题

一个经常出现的问题是：Gazebo 还没完全加载完 world，spawn_entity.py就开始尝试生成机器人，结果机器人模型生成失败，或者生成了但位置不对。在真实工作流里，要保证世界加载完成后再 spawn，可以在 launch 文件里加一个延时，或者用spawn_entity.py的-wait相关参数。

如果你做的场景比较复杂，比如 world 中有大量地形网格，Gazebo 加载已经花了 10 秒，而你的机器人脚本在 1 秒钟就开始尝试连接，那必然会出现模型加载失败。实际项目中，我一般会在 launch 里用一个带超时逻辑的 Executor，先检查是否有/world或/clock话题发布，再执行 spawn。这个方法比单纯 sleep 要靠谱，因为加载时间会随机器性能波动。

5.4 配合 PX4、ArduPilot 这类飞控仿真时的注意事项

很多人也想把自定义 world 用于无人机仿真。我是这样看待的：Gazebo 本身是“仿真环境”，飞控的特定功能是另一层逻辑，两者之间通过 MAVLink 或 ROS2 接口进行交互。如果你只做可视化，那么自定义 world 完全可以用于无人机的起飞、降落和姿态控制测试；但如果做视觉避障、目标追踪，就要在 world 中专门放置高质量纹理的目标区，并且要对光照和阴影进行单独调优，否则视觉传感器输出会不稳定。

在做无人机仿真时，强烈建议对 ground plane 以外的额外地面纹理保持谨慎。真实世界的地面是连续、稳定的，哪怕有杂草或碎石，也不会像某些粗糙纹理那样造成极大的视觉混淆。如果世界里的地面纹理过于花哨，特别是大面积高对比度图案，飞控的视觉里程计或光流传感器很容易输出虚假速度。模拟现实时，要尽量贴近真实的纹理分布。

6. 常见故障与排查方法：模型消失、抖动、加载缓慢的完整链路

6.1 模型缺失或找不到 model:// 路径

这是一个在自定义世界中出现频率最高的问题。具体表现是：Gazebo 启动时报错提示Unable to find model[my_building]，或者世界已经打开但场景中缺少一部分模型。

排查链路是这样的。第一步，先在模型目录下确认model.config中模型名字和目录名是否一致。第二步，确认环境变量GAZEBO_MODEL_PATH是否包含你的模型父目录。例如你的模型放在~/gazebo_models/my_building，那么需要添加的是~/gazebo_models，而不是~/gazebo_models/my_building。

在终端中验证一下很直接：

echo $GAZEBO_MODEL_PATH gz model --display my_building

如果gz model能显示模型信息，说明模型路径没问题。如果 gazebo 仍然启动找不到，再看 world 文件中写的 uri 是否多了或少了目录层级。url 里一个“ / ”写错，结果就是找不到。

6.2 世界加载后模型抖动或下沉到地面以下

模型抖动通常和物理引擎的接触求解有关。抖动高频出现的地形或静态模型，很可能是碰撞体和可视化几何不是完全贴合，导致接触点反复移动。还有一个很常见的原因是模型自身重量极小，而地面的摩擦和接触参数又不适合，导致机器人停在地面上时始终处于微小滑移状态。

如果出现模型整体下沉，多半是初始 pose 设得太低。比如你放一个半径 0.2 米的圆柱体，在 world 文件里的 pose 写的是<pose>0 0 0.1 0 0 0</pose>，此时圆柱底面已经低于地面平面，模型自然会穿地。把它改为0.2或者更高的值，再让物理引擎跑一下，能稳定住就可以。

但注意，这不是让你把所有物体都“悬空”放。模型初始位置过低会穿地，过高会掉下来弹几下。如果你发现物体落地后动都不动，可以考虑检查一下是否static设错了。一个本来是障碍物的模型如果被设成static=false，就会在重力作用下掉落到地面，但因为碰撞体接触，它不一定穿地，只是在反复震动。

6.3 世界加载缓慢，FPS 低下

世界文件比较大的时候，我通常先跑一下终端日志，看是哪个模型耗时最长。命令行输出里如果反复出现某个 mesh 文件读取或 texture 加载，那大概率是资源文件路径有问题，或者 mesh 三角面数量太多。

地形模型里，高度图分辨率直接决定加载时间。这里有个平衡问题，高度图太低地形不够真实，太高会导致地形网格顶点数爆增。以 100 米乘 100 米的场景为例，建议不要使用超过 1024x1024 的高度图，否则在普通笔记本上常常会卡到不可用。如果确实需要大范围精细地形，我建议切成小块分区域加载，而不是全部塞进同一个 world。

对于外部三维网格，我通常会先在 Blender 等工具里对网格进行精简，删掉不可见的面，再导出为 DAE 或 STL。一个极其常见的问题是 3D 扫描模型包含几十万甚至上百万三角面，但实际仿真只需要其中几千个面就能表达碰撞形状。这种场景下，视觉体可以用精细网格，碰撞体单独用一个简化过的粗略模型。注意一定要保证简化模型不要丢失关键的表面形状，否则碰撞会表现得很奇怪。

6.4 自定义世界跑起来比真实世界快或慢

Gazebo 里的实时性控制，由<physics>标签里的real_time_factor和real_time_update_rate决定。如果你发现无人机在自定义世界中特别飘，有时间步长的问题，也有可能是仿真时间跑得和真实时间不一致。real_time_update_rate控制的是物理引擎每秒钟更新的次数，通常设置为 1000，这样步长 0.001 秒就能一一对上。

在外场仿真中，如果你同时跑多个载具，并且每个载具上都有激光雷达和相机，物理计算和传感器渲染一般都会很吃力，此时可以把real_time_factor调低到 0.5 或者 0.2，让仿真比真实时间慢一点，以保证物理仿真稳定。但这同时会让真实时间的调试节奏变慢，你需要在场景复杂度和实时性之间做取舍。

6.5 观察日志是我最常用的辅助工具

最后分享一下我调试自定义世界的习惯。启动时加--verbose是我雷打不动的选项：

gazebo --verbose my_world.world

这样所有模型、插件的加载信息都会打印到终端。大部分问题在 verbose 模式里都会直接报出来，有时候虽然已经可以看到画面，但日志里其实带着一堆 warn 和 error，只是在图形界面中不容易察觉。比如某个模型缺少纹理、某个碰撞体使用了不支持的几何类型，这类 warning 如果不在最开始处理，后面可能会造成非常难排查的传感器阴影问题。

调试自定义世界看起来像是在跟 XML 和网格文件打交道，但本质上是在梳理你对物理世界的建模逻辑。你做的高度图地形、放的每一个障碍物、设定的每一组摩擦参数，都是为了让机器人算法尽可能在可信的训练场里学习。仿真环境的品质，直接影响你后续算法的结论是否能迁回真实世界。这也是我写了这么多字强调版本、路径、static、碰撞体和日志的原因。

我个人的经验是，自定义世界不是一次写完就完事的。最好把 world 文件、模型目录和启动脚本都放在同一个项目仓库里，配上一份简单的 README，说明这个场景的目标和需要调整的参数。这样过了半个月再回到项目时，或者团队其他人接手时，就能快速知道为什么这里要放一堵墙、为什么那个地形用了这个摩擦系数。做 Gazebo 仿真，最大的成本从来不是写那几行 XML，而是别人看到你这个信息残缺的场景后一头雾水。把这些信息补全后，自定义世界才能真正成为“可复用的仿真资产”。