解决 nav2_bringup tb3_simulation_launch.py 启动 Gazebo 失败：环境变量与模型路径排查指南

1. 问题现象与初步分析

最近在ROS 2 Humble环境下使用nav2_bringup包启动TurtleBot3仿真时，遇到了一个典型问题：执行ros2 launch nav2_bringup tb3_simulation_launch.py命令后，Rviz能够正常启动，但Gazebo要么完全打不开，要么打开后缺少TurtleBot3机器人模型。这个问题困扰了我好几天，经过多次尝试和排查，终于找到了根本原因和系统性的解决方案。

先说下我遇到的具体现象：在终端中按照官方文档的步骤操作，先设置环境变量再启动launch文件，结果Gazebo窗口完全没有出现。后来尝试在launch命令中加入headless:=False参数，Gazebo窗口倒是出来了，但场景中空空如也，本该出现的TurtleBot3机器人模型不见了踪影。这种"半成功"的状态反而更让人抓狂，因为至少完全失败时你知道哪里肯定出错了。

经过反复测试，我发现问题的核心集中在两个方面：环境变量设置和模型路径配置。特别是TURTLEBOT3_MODEL和GAZEBO_MODEL_PATH这两个关键环境变量，它们的正确设置与否直接决定了Gazebo能否正常启动并加载机器人模型。下面我就详细分享下具体的排查过程和解决方案。

2. 环境变量配置详解

2.1 关键环境变量解析

在TurtleBot3仿真环境中，有几个环境变量至关重要：

• TURTLEBOT3_MODEL：指定要使用的TurtleBot3型号，常见值有burger、waffle和waffle_pi。这个变量不仅影响Gazebo中加载的机器人模型，还会影响相关参数配置。

• GAZEBO_MODEL_PATH：告诉Gazebo去哪里寻找模型文件。当这个路径设置不正确时，Gazebo就找不到TurtleBot3的模型，导致场景中空空如也。

• ROS_DOMAIN_ID：在ROS 2中用于多机通信隔离，虽然不直接导致Gazebo启动失败，但设置不当可能引起其他奇怪问题。

我最初的问题就出在GAZEBO_MODEL_PATH的设置上。虽然按照文档设置了路径，但可能由于终端会话的问题，变量没有正确传递。后来发现，更可靠的做法是在同一个终端会话中一次性完成所有环境变量设置和启动命令。

2.2 环境变量设置的最佳实践

经过多次踩坑，我总结出环境变量设置的最佳方式：

# 一次性设置所有必要环境变量 source /opt/ros/humble/setup.bash export TURTLEBOT3_MODEL=waffle # 根据你的机器人型号调整 export GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:/opt/ros/humble/share/turtlebot3_gazebo/models # 立即在同一个终端中启动仿真 ros2 launch nav2_bringup tb3_simulation_launch.py

关键点在于：所有环境变量设置和启动命令必须在同一个终端会话中完成。如果先在一个终端设置变量，再在另一个终端启动，变量很可能不会生效。

3. 模型路径排查指南

3.1 验证模型文件是否存在

当Gazebo能够启动但看不到机器人模型时，首先要确认模型文件是否真的存在于指定路径。执行以下命令检查：

ls /opt/ros/humble/share/turtlebot3_gazebo/models

你应该能看到类似turtlebot3_burger、turtlebot3_waffle等目录。如果没有，可能需要重新安装相关包：

sudo apt install ros-humble-turtlebot3-gazebo

3.2 检查Gazebo模型路径

有时候即使设置了GAZEBO_MODEL_PATH，Gazebo也可能因为路径优先级问题找不到模型。可以在Gazebo启动后，通过其界面检查模型路径：

1. 点击Gazebo菜单栏的"Edit" > "Model Editor"
2. 在打开的窗口中查看左下角的"Insert"标签
3. 这里会列出Gazebo能找到的所有模型路径

如果没看到/opt/ros/humble/share/turtlebot3_gazebo/models路径，说明环境变量设置可能没生效。

3.3 使用verbose模式获取更多信息

在启动命令中添加verbose:=true参数可以让Gazebo输出更详细的日志，帮助定位问题：

ros2 launch nav2_bringup tb3_simulation_launch.py verbose:=true

在输出日志中搜索"Error"或"Warning"关键词，特别是与模型加载相关的错误信息。

4. 高级排查技巧

4.1 单独测试Gazebo启动

为了隔离问题，可以尝试单独启动Gazebo世界：

export TURTLEBOT3_MODEL=waffle ros2 launch turtlebot3_gazebo turtlebot3_world.launch.py

如果这样能正常启动并看到机器人模型，说明问题可能出在nav2_bringup的launch文件配置上。

4.2 检查launch文件参数

tb3_simulation_launch.py支持多个参数可以调整Gazebo行为，常用的有：

• headless：设为False强制显示Gazebo GUI
• world：指定要加载的世界文件
• use_sim_time：启用仿真时间

尝试这样启动：

ros2 launch nav2_bringup tb3_simulation_launch.py headless:=false use_sim_time:=true

4.3 清理Gazebo缓存

有时候Gazebo的缓存会导致奇怪的问题，可以尝试清理：

rm -rf ~/.gazebo

注意这会删除所有Gazebo缓存，包括你下载的其他模型。

5. 系统化解决方案

综合以上排查经验，我总结出一个可靠的启动流程：

1. 打开一个新终端
2. 一次性设置所有环境变量：

   source /opt/ros/humble/setup.bash export TURTLEBOT3_MODEL=waffle export GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:/opt/ros/humble/share/turtlebot3_gazebo/models

3. 启动仿真环境：

   ros2 launch nav2_bringup tb3_simulation_launch.py headless:=false

4. 如果还是看不到模型，检查Gazebo日志中的错误信息
5. 确保/opt/ros/humble/share/turtlebot3_gazebo/models目录存在且包含正确的模型文件

这套方法在我多次测试中都能可靠地启动完整的仿真环境。如果遇到特殊情况，可以根据前面的排查指南逐步定位问题根源。