故障排查

找不到 Gazebo 库

如果你看到此错误消息：

I cannot find any available 'gz' command:
 * Did you install any Gazebo library?
 * Did you set the GZ_CONFIG_PATH environment variable?
     E.g.: export GZ_CONFIG_PATH=$HOME/local/share/gz

你应该设置环境变量：

# replace <path_to_install_dir> to your Gazebo installation directory
GZ_CONFIG_PATH=<path_to_install_dir>/share/gz/

macOS

达到打开文件数上限的 ulimit 错误

使用 homebrew 安装时，你可能会看到以下错误消息：

Error: The maximum number of open files on this system has been reached. Use 'ulimit -n' to increase this limit.

如错误消息所示，运行以下命令并检查输出。默认值为 256，偏低。

ulimit -n

运行以下命令来提高打开文件数的 ulimit 限制，然后继续 homebrew 安装：

ulimit -n 10240

找不到 urdf_model.h 错误

安装所有依赖项并开始构建后，可能会遇到如下错误：

/Users/user/jetty_ws/src/sdformat/src/parser_urdf.cc:30:10: fatal error: 'urdf_model/model.h' file not found
#include <urdf_model/model.h>
         ^~~~~~~~~~~~~~~~~~~~
1 error generated.
make[2]: *** [src/CMakeFiles/sdformat9.dir/parser_urdf.cc.o] Error 1
make[1]: *** [src/CMakeFiles/sdformat9.dir/all] Error 2
make: *** [all] Error 2
Failed   <<< sdformat9 [ Exited with code 2 ]

首先通过运行以下命令检查 urdfdom 和 urdfdom_headers 是否已安装：

brew install urdfdom urdfdom_headers

然后，如果错误仍然存在，请运行以下命令，使用内部版本的 urdfdom 进行编译：

colcon build --cmake-args -DUSE_INTERNAL_URDF=ON --merge-install

此命令将忽略系统安装的 urdfdom，改用内部版本。

无法加载 .dylib 文件

运行 gz sim -s 命令时，可能会出现如下所示的错误：

Error while loading the library [/Users/jetty/jetty_ws/install/lib//libgz-physics6-dartsim-plugin.6.dylib]: dlopen(/Users/jetty/jetty_ws/install/lib//libgz-physics6-dartsim-plugin.6.dylib, 5): Library not loaded: @rpath/libIrrXML.dylib
  Referenced from: /usr/local/opt/assimp/lib/libassimp.5.dylib
  Reason: image not found
[Err] [Physics.cc:275] Unable to load the /Users/jetty/jetty_ws/install/lib//libgz-physics6-dartsim-plugin.6.dylib library.
Escalating to SIGKILL on [Gazebo Sim Server]

该问题与 macOS 系统完整性保护（System Integrity Protection, SIP）有关。解决方法是使用不同的 ruby 运行 gz，并确保该 ruby 已正确加载。

brew install ruby

# Add the following to ~/.bashrc
export PATH=/usr/local/Cellar/ruby/2.6.5/bin:$PATH

# Source ~/.bashrc in terminal
. ~/.bashrc

没有规则可以生成目标 '/usr/lib/libm.dylib', needed by 'lib/libgz-physics6-dartsim-plugin.6.1.0.dylib'. Stop.

尝试运行 brew outdated，然后运行 brew upgrade 可能会解决部分问题。

Ubuntu

内存不足问题

编译 Gazebo 期间可能会出现内存不足的情况，尤其是编译 gz-physics 时。为防止内存不足，可以限制并行任务数：

MAKEFLAGS="-j<Number of jobs> " colcon build --executor sequential

双 Intel 和 Nvidia GPU 系统的问题

如果使用的是 Intel/Nvidia 双显卡系统，仿真器可能在 Intel 显卡而非 Nvidia GPU 上运行。具体错误表现各异，可能出现阴影异常、激光扫描数据错误或其他渲染相关问题。

prime-select 命令行工具

Intel/Nvidia 混合显卡系统可以使用命令行工具 prime-select 进行配置。一种选择是始终使用 Nvidia：

sudo prime-select nvidia
# logout user session and login again

另一种选择是为 OpenGL 应用程序配置渲染卸载（render offload），使其使用 Nvidia。这样 X 桌面和所有普通应用程序仍由 Intel GPU 处理，但从终端启动的所有 OpenGL 应用程序（包括 Gazebo）都会在 Nvidia GPU 上渲染。

# place the lines in your .bashrc if you want the change to be permanent
export __NV_PRIME_RENDER_OFFLOAD=1
export __GLX_VENDOR_LIBRARY_NAME=nvidia
# logout user session and login again

nvidia-settings GUI 工具

nvidia-settings 是一个 GUI 程序，可帮助配置 Nvidia 显卡选项，并包含一些 Intel/Nvidia 混合显卡的控制选项：

在“PRIME Profiles”中选择“NVIDIA (Performance Mode)”即可让 Nvidia 显卡接管所有 GUI 应用程序。

“Application Profiles”可以按应用程序控制 Nvidia GPU 的使用。

无法创建渲染窗口

如果遇到类似“Unable to create the rendering window”的错误，可能是 OpenGL 版本过低。Gazebo Sim 默认使用 Ogre 2 渲染引擎，要求 OpenGL 3.3 及以上版本，推荐 4.3+。

可以通过查看 Ogre 2 日志（~/.gz/rendering/ogre2.log）来确认，其中应包含类似以下的错误：

"OGRE EXCEPTION(3:RenderingAPIException): OpenGL 3.3 is not supported. Please update your graphics card drivers."

也可以运行以下命令检查 OpenGL 版本：

glxinfo | grep "OpenGL version"

要启用 Ogre 2 支持，需要更新系统的 OpenGL 版本。正如 Ogre 日志所示，这可能需要更新显卡驱动程序。

如果在使用 Ogre 2 运行 Gazebo 时仍遇到 OpenGL 问题，可能是驱动程序不支持某些扩展，或者正在虚拟机中运行。此时可以尝试禁用 DRI：

export LIBGL_DRI3_DISABLE=1

或强制软件渲染

export LIBGL_ALWAYS_SOFTWARE=1

如果使用的是 MESA 驱动程序，还可以尝试覆盖 OpenGL 版本：

# Override GL version to 3.3
export MESA_GL_VERSION_OVERRIDE=3.3

# Alternatively, select Core + Forward compatible profile with 3.3
export MESA_GL_VERSION_OVERRIDE=3.3FC

有关更多信息，请参阅 MESA 环境变量文档。

osrfoundation 仓库中的 Ogre 2 deb 包基于 Ogre v2-3 分支的一个 fork 构建，其中包含 deb 打包所需的更改，并允许与 Ogre 1.x 共存安装。代码地址如下：

https://github.com/osrf/ogre-2.3-release

不过，使用 Ogre 1 应该没有问题。可以尝试用 Ogre 1 而非 Ogre 2 运行来验证，例如：

gz sim -v 3 shapes.sdf --render-engine ogre

如果能正常加载，之后运行 Gazebo 时加上 --render-engine ogre 选项即可继续使用 Ogre 1。

Wayland 问题

Gazebo 中 Ogre 和 Qt 的交互存在一个已知问题，导致 Wayland 下无法正常工作。可能看到如下错误消息：

Unable to create the rendering window: OGRE EXCEPTION(3:RenderingAPIException): currentGLContext was specified with no current GL context in GLXWindow::create at ./RenderSystems/GL3Plus/src/windowing/GLX/OgreGLXWindow.cpp (line 165)

一种解决方法是设置 QT_QPA_PLATFORM=xcb，例如：

QT_QPA_PLATFORM=xcb gz sim -v 4 shapes.sdf

另一种可尝试的方法是确保 Gazebo 通过 XWayland 启动，即取消设置 WAYLAND_DISPLAY 环境变量，例如：

env -u WAYLAND_DISPLAY gz sim -v 4 shapes.sdf

EGL 警告

启动时，Gazebo 会输出如下 EGL 警告消息：

libEGL warning: DRI2: failed to create dri screen

这是 Ogre 2 在初始化期间枚举设备、查询 EGL 支持时输出的，可以忽略。Gazebo 会继续正常运行，不受影响。

网络配置问题

网络配置不当可能导致 Gazebo 打开窗口后无响应。可以通过运行 gz sim -v 4 shapes.sdf 并检查以下输出来诊断：

[GUI] [Dbg] [Gui.cc:343] GUI requesting list of world names. The server may be busy downloading resources. Please be patient.

要解决此问题，请按照 ROS Enable Multicast 中的步骤启用多播（multicast）。

Windows

VisualStudioVersion 未设置，请在 Visual Studio 命令提示符中运行

当尝试编译 Gazebo 时，可能会在终端中看到类似这样的错误：

VisualStudioVersion is not set, please run within a Visual Studio Command Prompt.

在这种情况下，执行以下命令之一：

• CMD

    "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64

• PowerShell:

pushd "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools"
cmd /c "VsDevCmd.bat&set" |
foreach \{
  if ($_ -match "=") \{
    $v = $_.split("="); set-item -force -path "ENV:\$($v[0])"  -value "$($v[1])"
  \}
\}
popd

运行 colcon 时出现大量 setuptools 错误

调用 colcon 构建包时，可能会遇到大量类似如下的 Python 错误：

> colcon graph
Traceback (most recent call last):
  File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'setuptools.extern'
[10.385s] colcon.colcon_core.package_identification ERROR Exception in package identification extension 'python_setup_py' in 'conda\Lib\site-packages\adodbapi': Command '['D:\\programovani\\gz-ws\\conda\\python.exe', '-c', "import sys;from setuptools.extern.packaging.specifiers import SpecifierSet;from distutils.core import run_setup;dist = run_setup(    'setup.py', script_args=('--dry-run',), stop_after='config');skip_keys = ('cmdclass', 'distclass', 'ext_modules', 'metadata');data = \{    key: value for key, value in dist.__dict__.items()     if (        not key.startswith('_') and         not callable(value) and         key not in skip_keys and         key not in dist.display_option_names    )\};data['metadata'] = \{    k: v for k, v in dist.metadata.__dict__.items()     if k not in ('license_files', 'provides_extras')\};sys.stdout.buffer.write(repr(data).encode('utf-8'))"]' returned non-zero exit status 1.

这些错误信息相当晦涩，没有指向根本原因。根本原因是：你可能在与 Gazebo 源代码 src 目录同级的目录下创建了 conda env 目录（即使用了 conda create --prefix ... 在非默认位置创建 env）。

解决方案是将 conda env 目录上移一级。

例如，以下是存在问题的文件夹结构：

gz-ws\
  conda\  # The conda env
  src\    # The Gazebo sources
    gz-sim\

修复方法是改为如下结构：

gz-ws\
  src\
    gz-sim\
conda\