安装故障排除

安装故障排除技术根据其适用的平台进行分类。

常规 

常规故障排除技术适用于所有平台。

启用多播

为了通过 DDS 成功通信，使用的网络接口必须启用多播。我们在过去的经验中看到，使用环回适配器时，默认情况下可能不一定启用此功能（在 Ubuntu 或 OSX 上）。请参阅`原始问题 <https://github.com/ros2/ros2/issues/552>`__ 或`ros-answers 上的对话 <https://answers.ros.org/question/300370/ros2-talker-cannot-communicate-with-listener/>`__。您可以使用 ROS 2 工具验证当前设置是否允许多播：

在终端 1 中：

ros2 multicast receive

在终端 2 中：

ros2 multicast send

如果第一个命令没有返回类似的响应：

Received from xx.xxx.xxx.xx:43751: 'Hello World!'

那么您将需要更新防火墙配置以允许使用“ufw <https://help.ubuntu.com/community/UFW>”进行多播。

sudo ufw allow in proto udp to 224.0.0.0/4
sudo ufw allow in proto udp from 224.0.0.0/4

您可以使用：code:ifconfig 工具检查网络接口是否启用了多播标志，并在标志部分查找：code:MULITCAST：

eno1: flags=4163<...,MULTICAST>
   ...

导入失败，系统中没有库

有时 rclpy 导入失败，因为未找到预期的 C 扩展库。如果是这样，请将目录中的库与错误消息中提到的库进行比较。假设存在具有相似名称的文件（前缀相同，如 _rclpy. 和后缀相同，如 .so，但 Python 版本/架构不同），则您使用的 Python 解释器与用于构建 C 扩展的解释器不同。确保使用与用于构建二进制文件相同的 Python 解释器。

例如，这种不匹配可能会在操作系统更新后出现。然后，重建工作区可能会解决问题。

Linux 

内部编译器错误

如果您在内存受限的平台（如 Raspberry PI）上尝试编译时遇到 ICE，您可能需要构建单线程（在构建调用前加上“MAKEFLAGS=-j1”前缀）。

内存不足

当前形式的“ros1_bridge”需要 4Gb 的可用 RAM 才能编译。

如果您没有那么多可用的 RAM，建议在该文件夹中使用“COLCON_IGNORE”并跳过其编译。

多主机干扰

如果您在同一网络上运行多个实例，可能会受到干扰。为了避免这种情况，您可以将环境变量“ROS_DOMAIN_ID”设置为不同的整数，默认值为零。这将为您的系统定义 DDS 域 ID。

异常来源 setup.bash

如果在从源代码构建后尝试获取环境源时遇到异常，请尝试使用以下方法升级“colcon”相关包

colcon version-check  # check if newer versions available
sudo apt install python3-colcon* --only-upgrade  # upgrade installed colcon packages to latest version

Anaconda Python 冲突

conda 无法与 ROS 2 协同工作。确保您的 PATH 环境变量中没有任何 conda 路径。您可能需要检查您的 .bashrc 中是否有此行并将其注释掉。

无法启动 rviz2

rviz2 可能无法在 Wayland 显示系统上启动，并出现以下错误：

QSocketNotifier: Can only be used with threads started with QThread
[INFO] [1714730141.758659580] [rviz2]: Stereo is NOT SUPPORTED
[INFO] [1714730141.758813709] [rviz2]: OpenGl version: 3.1 (GLSL 1.4)
[ERROR] [1714730141.797879232] [rviz2]: rviz::RenderSystem: error creating render window: RenderingAPIException: Invalid parentWindowHandle (wrong server or screen) in GLXWindow::create at ./.obj-aarch64-linux-gnu/ogre_vendor-prefix/src/ogre_vendor/RenderSystems/GLSupport/src/GLX/OgreGLXWindow.cpp (line 246)
...
[ERROR] [1714730141.808124283] [rviz2]: Unable to create the rendering window after 100 tries
terminate called after throwing an instance of 'std::runtime_error'
  what():  Unable to create the rendering window after 100 tries
Aborted (core dumped)

这是由于 Wayland 和 RViz2 不兼容造成的。您可以通过在 X11 兼容模式下运行 RViz2 来解决此问题：

QT_QPA_PLATFORM=xcb rviz2

macOS 

使用 `pyenv` 时出现分段错误

pyenv 似乎默认使用 .a 文件构建 Python，但这会导致 rclpy 出现问题，因此建议在使用 pyenv 时在 macOS 上启用框架构建 Python：

https://github.com/pyenv/pyenv/wiki#how-to-build-cpython-with-framework-support-on-os-x

库未加载；图像未找到

如果您在运行时（运行测试或运行节点）看到库加载问题，例如以下内容：

ImportError: dlopen(.../ros2_<distro>/ros2-osx/lib/python3.7/site-packages/rclpy/_rclpy.cpython-37m-darwin.so, 2): Library not loaded: @rpath/librcl_interfaces__rosidl_typesupport_c.dylib
  Referenced from: .../ros2_<distro>/ros2-osx/lib/python3.7/site-packages/rclpy/_rclpy.cpython-37m-darwin.so
  Reason: image not found

那么您可能已启用系统完整性保护。按照`这些说明<https://developer.apple.com/library/content/documentation/Security/Conceptual/System_Integrity_Protection_Guide/ConfiguringSystemIntegrityProtection/ConfiguringSystemIntegrityProtection.html>`__ 禁用系统完整性保护 (SIP)。

Qt 构建错误：`未知类型名称 'Q_ENUM'`

如果您看到与 Qt 相关的构建错误，例如：

In file included from /usr/local/opt/qt/lib/QtGui.framework/Headers/qguiapplication.h:46:
/usr/local/opt/qt/lib/QtGui.framework/Headers/qinputmethod.h:87:5: error:
      unknown type name 'Q_ENUM'
    Q_ENUM(Action)
    ^

您可能使用的是 qt4 而不是 qt5：请参阅 https://github.com/ros2/ros2/issues/441

使用 Homebrew 安装 opencv（以及 libjpeg、libtiff 和 libpng）时缺少符号

如果您安装了 opencv，您可能会得到以下信息：

dyld: Symbol not found: __cg_jpeg_resync_to_restart
  Referenced from: /System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO
  Expected in: /usr/local/lib/libJPEG.dylib
 in /System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO
/bin/sh: line 1: 25274 Trace/BPT trap: 5       /usr/local/bin/cmake

如果是这样，要构建你必须执行以下操作：

$ brew unlink libpng libtiff libjpeg

但这会破坏 opencv，因此您还需要更新它才能继续工作：

$ sudo install_name_tool -change /usr/local/lib/libjpeg.8.dylib /usr/local/opt/jpeg/lib/libjpeg.8.dylib /usr/local/lib/libopencv_highgui.2.4.dylib
$ sudo install_name_tool -change /usr/local/lib/libpng16.16.dylib /usr/local/opt/libpng/lib/libpng16.16.dylib /usr/local/lib/libopencv_highgui.2.4.dylib
$ sudo install_name_tool -change /usr/local/lib/libtiff.5.dylib /usr/local/opt/libtiff/lib/libtiff.5.dylib /usr/local/lib/libopencv_highgui.2.4.dylib
$ sudo install_name_tool -change /usr/local/lib/libjpeg.8.dylib /usr/local/opt/jpeg/lib/libjpeg.8.dylib /usr/local/Cellar/libtiff/4.0.4/lib/libtiff.5.dylib

第一个命令是必要的，以避免针对系统 libjpeg（等等）构建的东西从 /usr/local/lib 中获取版本。其他命令正在更新 Homebrew 构建的东西，以便它们可以在没有 /usr/local/lib 的情况下找到 libjpeg（等等）的版本。

Xcode-select 错误：工具“xcodebuild”需要 Xcode，但活动开发者目录是一个命令行实例

如果您最近安装了 Xcode，您可能会遇到此错误：

Xcode: xcode-select: error: tool 'xcodebuild' requires Xcode,
but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance

要解决此错误，您需要：

仔细检查是否已安装命令行工具：

$ xcode-select --install

在终端中输入以下内容接受 Xcode 的条款和条件：

$ sudo xcodebuild -license accept

确保 Xcode 应用位于 /Applications 目录中（而不是 /Users/{user}/Applications）
使用以下命令将 xcode-select 指向 Xcode 应用开发者目录：

$ sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

rosdep 安装错误 `homebrew: 无法检测到 [qt5] 是否安装成功`

在按照创建工作区教程操作时，您可能会遇到以下错误，指出 rosdep 无法安装 Qt5。

$ rosdep install -i --from-path src --rosdistro rolling -y
executing command [brew install qt5]
Warning: qt 5.15.0 is already installed and up-to-date
To reinstall 5.15.0, run `brew reinstall qt`
ERROR: the following rosdeps failed to install
  homebrew: Failed to detect successful installation of [qt5]

该错误似乎源于“链接问题<https://github.com/ros-infrastructure/rosdep/issues/490#issuecomment-334959426>” ，可以通过运行以下命令解决。

$ cd /usr/local/Cellar
$ sudo ln -s qt qt5

运行“rosdep”命令现在应该可以正常执行：

$ rosdep install -i --from-path src --rosdistro rolling -y
#All required rosdeps installed successfully

Windows 

即使系统中存在库，导入也会失败

有时，由于系统中缺少某些 DLL，rclpy 无法导入。如果是这样，请确保安装安装说明的“安装先决条件”部分中列出的所有依赖项。

如果您从二进制文件安装，则可能需要更新依赖项：它们必须与用于构建二进制文件的版本相同。

如果您仍然遇到问题，可以使用 Dependencies 工具来确定系统上缺少哪些依赖项。使用该工具加载相应的 .pyd 文件，它应该会报告不可用的 DLL 模块。确保在执行该工具之前获取当前工作区，否则将出现未解析的 ROS DLL 文件。使用此信息安装其他依赖项或根据需要调整路径。

CMake 错误设置修改时间

如果在安装文件时遇到 CMake 错误“文件 INSTALL 无法设置修改时间…”，则可能是防病毒软件或 Windows Defender 干扰了构建。例如，对于 Windows Defender，您可以列出要排除的工作区位置，以防止它扫描这些文件。

260 个字符的路径限制

The input line is too long.
The syntax of the command is incorrect.

根据您的目录层次结构，从源代码或您自己的库构建 ROS 2 时，您可能会看到路径长度限制错误。

要允许更深的路径长度：

运行“regedit.exe”，导航到“ComputerHKEY_LOCAL_MACHINESYSTEMCurrentControlSetControlFileSystem”，并将“LongPathsEnabled”设置为 0x00000001 (1)。

按 Windows 键并输入“编辑组策略”。导航到本地计算机策略 > 计算机配置 > 管理模板 > 系统 > 文件系统。右键单击“启用 Win32 长路径”，单击编辑。在对话框中，选择已启用并单击确定。

关闭并打开终端以重置环境并尝试再次构建。

CMake 软件包无法找到 asio、tinyxml2、tinyxml 或 eigen

我们发现，有时“asio”、“tinyxml2”等 chocolatey 软件包不会添加重要的注册表项，因此 CMake 在构建 ROS 2 时无法找到它们。

我们尚未确定根本原因，但卸载 chocolatey 软件包（如果第一次卸载失败，则使用“-n”），然后重新安装它们将解决此问题。

patch.exe 打开一个新的命令窗口并要求管理员权限

这也会导致需要使用补丁的软件包的构建失败，即使您允许它使用管理员权限。

choco uninstall patch; colcon build --cmake-clean-cache - 这是 GNU Patch For Windows 软件包中的一个错误。如果未安装此软件包，则构建过程将改为使用 git 分发的补丁版本。

无法加载 Fast RTPS 共享库

Fast RTPS 需要 msvcr20.dll，它是 Visual C++ Redistributable Packages for Visual Studio 2013 的一部分。虽然它通常在 Windows 10 中默认安装，但我们知道某些类似 Windows 10 的版本默认没有安装它（例如：Windows Server 2019）。如果您没有安装它，您可以从`这里 <https://www.microsoft.com/en-us/download/details.aspx?id=40784>`_ 下载它。

无法创建进程

如果运行 ROS 二进制文件出现错误：

| failed to create process.

很可能是没有找到 Python 解释器。对于每个可执行文件，都会使用随附脚本的 shebang（第一行），因此请确保 Python 在预期路径下可用（默认值：“C:Python38”）。

二进制安装特定

如果您的示例由于缺少 DLL 而无法启动，请验证来自外部依赖项（例如 OpenCV）的所有库是否位于您的“PATH”变量内。
如果您忘记从终端调用“local_setup.bat”文件，演示程序很可能会立即崩溃。

使用 WSL2 运行 RViz

如果您使用 WSL2 在 Windows 上运行 ROS 2，您可能会遇到运行 RViz 的问题，如下所示：

$ rviz2
[INFO] [1695823660.091830699] [rviz2]: Stereo is NOT SUPPORTED
[INFO] [1695823660.091943524] [rviz2]: OpenGl version: 4.1 (GLSL 4.1)
D3D12: Removing Device.
Segmentation fault

解决此问题的一个可能方法是强制 RViz 使用软件渲染：

$ export LIBGL_ALWAYS_SOFTWARE=true
$ rviz2
[INFO] [1695823660.091830699] [rviz2]: Stereo is NOT SUPPORTED