安装故障排除

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

平台

通用
Linux
macOS
Windows

通用 

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

启用多播

为了通过DDS成功通信，使用的网络接口必须启用组播功能。在过去的经验中，我们发现当使用环回适配器（在Ubuntu或OSX上）时，默认情况下可能未启用组播功能。请参阅原始问题或 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 版本/架构），则表示您正在使用与用于构建 C 扩展的 Python 解释器不同的 Python 解释器。请确保使用与构建二进制文件时相同的 Python 解释器。

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

Linux 

内部编译器错误

如果在像树莓派这样的内存受限平台上尝试编译时遇到内部编译器错误（ICE），您可能希望使用单线程构建（在构建命令前加上 MAKEFLAGS=-j1）。

内存不足

目前的 ros1_bridge 需要4GB的可用内存进行编译。如果您没有足够的可用内存，建议在该文件夹中使用 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

macOS 

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

pyenv``似乎默认使用.a``文件构建Python，但这会导致``rclpy``出现问题，因此建议在使用``pyenv``时在macOS上启用Frameworks构建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

那么您可能已启用系统完整性保护（System Integrity Protection）。按照这些说明禁用系统完整性保护（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构建的内容，使其能够找到libjpeg（等等）的版本，而不必将它们放在/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 应用程序的开发者目录：

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

qt_gui_cpp 错误：SIP 绑定生成器不可用

构建 qt_gui_cpp 时可能会出现以下类似的错误：

--- stderr: qt_gui_cpp

CMake Error at src/CMakeLists.txt:10 (message):
  No Python binding generator found.

---
Failed   <<< qt_gui_cpp [ Exited with code 1 ]

要解决此问题，请按照这些步骤安装 RQt 的依赖项。

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

在遵循创建工作空间教程时，您可能会遇到以下错误，指出 rosdep 无法安装 Qt5。

$ rosdep install -i --from-path src --rosdistro humble -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 humble -y
#All required rosdeps installed successfully

Windows 

即使系统中存在该库，导入仍然失败

有时候由于系统上缺少某些 DLL 文件，导致无法导入 rclpy。如果出现这种情况，请确保安装了安装指南中“安装先决条件”部分列出的所有依赖项。

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

如果您仍然遇到问题，您可以使用 Dependencies 工具来确定您的系统缺少哪些依赖项。使用该工具加载相应的 .pyd 文件，它将报告不可用的 DLL 模块。在执行工具之前，请确保当前的工作空间已被激活，否则将出现未解决的 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，点击编辑。在对话框中，选择已启用并点击确定。

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

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

我们发现有时候``asio``、tinyxml2``等的chocolatey软件包没有添加重要的注册表项，导致在构建ROS 2时CMake无法找到它们。我们还没有找到根本原因，但是卸载chocolatey软件包（如果首次卸载失败，则使用-n``参数），然后重新安装它们可以解决这个问题。

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

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

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

无法加载 Fast RTPS 共享库

Fast RTPS 需要 msvcr20.dll，它是 ``Visual C++ Redistributable Packages for Visual Studio 201

无法创建进程

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

| failed to create process.

很可能找不到 Python 解释器。对于每个可执行文件，将使用伴随脚本的 shebang（第一行）；因此，请确保 Python 在预期路径下可用（默认路径：C:\Python38\）。

二进制安装特定

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