安装故障排除

安装相关的故障排除技巧按照其适用的平台进行分类。

通用

以下通用故障排除技巧适用于所有平台。

启用多播（multicast）

为了通过 DDS 成功通信，所使用的网络接口必须启用多播。根据经验，回环适配器（loopback adapter）在 Ubuntu 或 macOS 上可能默认未启用多播。参见原始 issue 或 ros-answers 上的讨论。

你可以使用 ROS 2 工具来验证当前设置是否允许多播：

在终端 1 中：

ros2 multicast receive

在终端 2 中：

ros2 multicast send

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

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

那么你需要更新防火墙配置，使用 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

你可以使用 ifconfig 工具检查网络接口是否启用了多播标志，在 flags 部分查找 MULTICAST：

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

系统中不存在库时导入失败

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

例如，这种不匹配可能在操作系统更新后出现。此时，重新构建工作空间可能即可解决问题。

Linux

内部编译器错误

如果你在 Raspberry Pi 等内存受限的平台上编译时遇到 ICE（内部编译器错误），可能需要单线程构建（在构建命令前加上 MAKEFLAGS=-j1）。

多主机干扰

如果你在同一网络上运行多个实例，可能会出现干扰。为避免这种情况，可以将环境变量 ROS_DOMAIN_ID 设置为不同的整数值（默认值为零），以此来定义你系统的 DDS domain id。

执行 setup.bash 时出现异常

如果你在从源码构建后尝试 source 环境时遇到异常，请尝试使用以下命令升级 colcon 相关包：

colcon version-check  # 检查是否有更新的版本
sudo apt install python3-colcon* --only-upgrade  # 将已安装的 colcon 包升级到最新版本

混合使用 conda 和 apt 的 Python 冲突

在使用 ROS 2 时，将 apt 安装的包与 conda 安装的包混合使用并不可行。如果你使用的是 ROS 2 的官方 apt 二进制包，请确保 PATH 环境变量中不包含任何 conda 路径。你可能需要检查 .bashrc 文件并注释掉相关行。

另一方面，在 Windows 上，官方的 ROS 2 安装过程通过 pixi 包管理器使用 conda 包，这可以正常工作，因为不存在不同包管理器的混用。

ROS 2 的 conda 包可以由社区构建（例如由社区维护的 RoboStack 项目），但官方不提供 ROS 2 的 conda 包。

无法启动 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` 时出现段错误（Segmentation fault）

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

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

库未加载；镜像未找到（Library not loaded; image not found）

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

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

那么你可能启用了系统完整性保护（System Integrity Protection，SIP）。请按照这些说明禁用 SIP。

Qt 构建错误：`unknown type name '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 中的版本也能找到所需库。

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 应用的 Developer 目录：

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

rosdep 安装错误 `homebrew: Failed to detect successful installation of [qt5]`

在跟随创建工作空间教程时，你可能会遇到以下错误，提示 rosdep 无法安装 Qt5。

$ rosdep install -i --from-path src --rosdistro {DISTRO} -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]

此错误似乎源于一个链接问题，可以通过运行以下命令解决：

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

现在再次运行 rosdep 命令应该可以正常执行：

rosdep install -i --from-path src --rosdistro {DISTRO} -y

该命令应返回：

#All required rosdeps installed successfully

Windows

系统中存在库但导入仍然失败

有时 rclpy 导入失败是因为系统中缺少某些 DLL。如果出现这种情况，请确保安装了安装说明中”安装前置条件”（Installing prerequisites）部分列出的所有依赖。

如果你是通过二进制包安装的，可能需要更新依赖：版本必须与构建二进制包时使用的一致。

如果仍有问题，你可以使用 Dependencies 工具来确定系统中缺少哪些依赖。使用该工具加载相应的 .pyd 文件，它会报告不可用的 DLL 模块。请确保在运行该工具之前已 source 当前工作空间，否则会存在无法解析的 ROS DLL。根据这些信息安装额外的依赖，或根据需要调整路径。

CMake 设置修改时间错误

如果你在安装文件时遇到 CMake 错误 file INSTALL cannot set modification time on ...，很可能是杀毒软件或 Windows Defender 干扰了构建。例如，对于 Windows Defender，你可以将工作空间位置添加到排除列表中，防止其扫描这些文件。

260 字符路径长度限制

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

根据你的目录层级，在从源码构建 ROS 2 或你自己的库时，可能会遇到路径长度限制错误。

要允许更长的路径：

运行 regedit.exe，导航到 Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem，将 LongPathsEnabled 设置为 0x00000001 (1)。

按下 Windows 键并输入 Edit Group Policy。导航到 Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem。右键点击 Enable Win32 long paths，点击 Edit。在对话框中选择 Enabled，然后点击 OK。

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

无法加载 Fast RTPS 共享库

Fast RTPS 需要 msvcr20.dll，它是 Visual C++ Redistributable Packages for Visual Studio 2013 的一部分。虽然它在 Windows 10 中通常默认安装，但部分类似 Windows 10 的版本（例如 Windows Server 2019）默认未安装。如果你没有安装，可以从这里下载。

无法创建进程（Failed to create process）

如果运行 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