Debian 12(bookworm)上为树莓派4B编译ROS2 Humble：从依赖解决到系统集成

字节杂耍者

452人浏览 · 2026-03-08 00:55:10

字节杂耍者 · 2026-03-08 00:55:10 发布

1. 为什么要在树莓派4B上用Debian 12编译ROS2 Humble？

如果你和我一样，是个喜欢折腾树莓派和机器人的开发者，那你肯定对ROS2不陌生。ROS2 Humble Hawksbill是一个长期支持版本，稳定性和社区支持都很好，是很多机器人项目的首选。但官方主要支持Ubuntu 22.04，对于想在树莓派上跑Debian 12（代号Bookworm）的朋友来说，直接安装预编译包的路子基本走不通。为什么非要这么干呢？我自己的经验是，Debian 12作为树莓派官方推荐的操作系统之一，它更轻量、更“干净”，对硬件资源的占用比带桌面环境的Ubuntu要友好得多，尤其适合作为机器人或边缘计算设备的“大脑”。而且，从源码编译ROS2虽然过程繁琐，但你能获得对系统更深层次的控制，可以针对树莓派4B的ARMv8架构进行优化，裁剪掉不需要的组件，最终得到一个更精简、更高效的系统。

不过，这条路并不平坦。Debian 12的软件仓库版本和Ubuntu 22.04有差异，很多ROS2依赖的库版本对不上号，或者干脆就找不到。ARM架构的编译环境也和x86_64不同，一些预编译的二进制依赖（比如某些DDS中间件）可能不提供ARM版本。这就意味着，你得像搭积木一样，从最底层开始，一块一块地把所有依赖都手动解决掉，然后才能开始编译ROS2本体。这个过程充满了“坑”，比如编译到一半某个库报错，或者链接时找不到符号。但别担心，我花了大量时间，在树莓派4B 8GB版本上从头到尾走通了这条路，把踩过的坑和解决方案都整理了出来。这篇文章的目的，就是手把手带你完成从纯净的Debian 12系统开始，到成功运行turtlesim小海龟的完整过程。无论你是学生、研究者还是爱好者，只要跟着步骤走，都能在自己的树莓派上搭建起一个可用的ROS2 Humble开发环境。

2. 编译前的系统准备与依赖大扫除

在开始编译ROS2这座“大厦”之前，我们必须把地基打牢。这个地基就是树莓派4B上运行的Debian 12系统以及所有必要的编译工具和库。官方教程里的apt-get install命令在Debian上可能会大面积失效，我们需要根据Debian 12的仓库情况灵活调整。

2.1 基础编译环境搭建

首先，确保你的系统是最新的。用SSH连上你的树莓派，或者接上键盘显示器，打开终端。

sudo apt update && sudo apt upgrade -y
sudo apt autoremove -y

接下来，安装最核心的编译工具链。git用于拉取代码，cmake是ROS2构建系统的核心，python3-pip则是Python包管理器。

sudo apt-get install -y git cmake python3-pip

这里第一个“坑”可能就来了。Debian 12自带的pip版本可能比较新，在安装某些老版本的Python包时会有兼容性问题。如果遇到报错，可以尝试降级pip或者使用pip3 install --break-system-packages（如果提示相关警告）。我个人更倾向于在用户空间操作，避免污染系统Python环境，但为了编译ROS2系统级组件，有时不得不使用sudo。

2.2 Python依赖的“坑”与填坑指南

ROS2大量使用Python，所以Python依赖的安装是关键一步，也是错误高发区。原始文章里列出了一长串pip3 install命令，但在Debian 12上，你需要格外小心。

# 安装一些基础的Python包，注意版本适配
sudo pip3 install defusedxml rospkg netifaces

安装empy时，原始文章指定了3.3.2版本。这是因为新版本的empy可能和ROS2的某些组件不兼容。如果直接pip3 install empy安装的是新版，编译时可能会报错。所以指定版本是个好习惯。

sudo pip3 install empy==3.3.2

接下来是加密相关的包。pycrypto这个包比较老，可能安装失败，我们可以用功能更现代的pycryptodome和pycryptodomex来替代。

sudo pip3 install pycryptodome pycryptodomex

安装gnupg（GNU Privacy Guard的Python绑定）时，你可能会遇到最大的麻烦。原始文章提到了ReadTimeoutError，这是因为网络连接超时，多试几次sudo pip3 install gnupg或许能成功。但如果遇到setuptools相关的错误，就需要手动安装一个兼容版本的setuptools。下面这个方法是经过实测有效的：

# 如果pip安装gnupg失败，并提示setuptools问题，执行以下步骤
wget https://pypi.python.org/packages/source/s/setuptools/setuptools-69.1.1.tar.gz
tar -zxvf setuptools-69.1.1.tar.gz
cd setuptools-69.1.1/
python3 setup.py build
sudo python3 setup.py install
# 然后回头再次尝试安装gnupg，有时需要尝试两次
sudo pip3 install gnupg

这个过程体现了在非标准平台上编译的常态：遇到错误，搜索错误信息，找到根本原因（这里是setuptools版本不匹配），然后手动修复底层依赖。记住，耐心是成功编译的一半。

2.3 系统库依赖：一场与包管理器的“谈判”

Python依赖搞定后，就是庞大的系统库依赖。原始文章给出的命令列表非常宝贵，但直接复制粘贴到Debian 12上，大概率会有一半的包提示“无法定位软件包”。这是因为包名或者版本号在Debian和Ubuntu的仓库中不同。我们的策略是：能装则装，找不到就找替代品或从源码编译。

首先，是一些通用工具和基础库：

sudo apt-get install -y zip build-essential

接下来是关键库。例如Boost库，在Ubuntu 22.04上是libboost1.74-all-dev，但在Debian 12中，你可能需要安装libboost-all-dev，它会自动安装仓库中可用的最新稳定版（可能是1.74或更高）。同样，日志库liblog4cxx在Debian中包名可能略有不同，如果找不到liblog4cxx15，可以尝试搜索apt search liblog4cxx来找到正确的包名。

# 尝试安装，如果找不到，记录下缺失的包名，我们稍后处理
sudo apt-get install -y libboost-all-dev
sudo apt-get install -y liblog4cxx-dev libtinyxml2-dev libyaml-cpp-dev

对于像ogre-1.12（3D渲染引擎）这样的图形库，在无桌面的Debian服务器版上可能比较棘手。你可以尝试安装libogre-1.12-dev，如果失败，可以考虑从源码编译Ogre 1.12，或者如果你的机器人应用不涉及复杂的3D可视化（比如不用RViz），可以在后续编译ROS2时跳过依赖它的包（如rviz2）。

# 尝试安装Ogre，失败是常态，不必慌张
sudo apt-get install -y libogre-1.12-dev

其他一些重要的开发库：

sudo apt-get install -y libpoco-dev libcurl4-openssl-dev liborocos-kdl-dev
sudo apt-get install -y libbullet-dev libopencv-dev libeigen3-dev
sudo apt-get install -y libbz2-dev liblzma-dev libsdl2-dev
sudo apt-get install -y libgpgme-dev libuvc-dev  # 用于硬件访问和加密

对于pyqt5，如果你想在树莓派上运行一些基于GUI的ROS2工具（如RQt），就需要安装。但在无桌面环境或资源紧张时，这步可以省略或部分安装。原始文章的命令sudo apt-get install pyqt5*会尝试安装所有相关包，可能带来大量不必要的依赖。更精确的做法是只安装核心开发包：

sudo apt-get install -y pyqt5-dev-tools qttools5-dev-tools python3-pyqt5

最后，别忘了安装一些代码检查和质量控制工具，它们在编译过程中不是必须的，但对开发者有用：

sudo apt-get install -y cppcheck clang-format uncrustify doxygen

核心策略：每执行一条apt-get install命令，都观察输出。对于“无法定位软件包”的错误，不要立刻停止。记下缺失的包名，然后通过apt search <包名关键词>或上网搜索“Debian 12 <包名>”来查找替代方案。有时，你需要安装一个不同版本号的包（如libyaml-cpp0.7变成libyaml-cpp0.8），有时则需要添加第三方仓库（如ROS官方仓库本身），有时则必须放弃apt安装，转向源码编译。这个过程就像拼图，需要耐心和搜索能力。

3. 获取ROS2 Humble源码与依赖管理

当系统依赖准备得七七八八后，我们就可以开始处理ROS2本身的代码了。这里我们选择从源码构建，以获得最大的灵活性和对ARM架构的适配。

3.1 创建工作空间与获取源码

首先，安装一些用于获取和管理ROS2源码的工具：

sudo apt-get install -y python3-rosinstall-generator python3-vcstools

创建一个专门的工作空间目录。我习惯放在用户主目录下，方便管理。

mkdir -p ~/ros2_humble/src
cd ~/ros2_humble

ROS2使用一个名为ros2.repos的文件来定义所有组件的源代码仓库地址和版本。我们下载Humble版本的这个文件。

wget https://raw.githubusercontent.com/ros2/ros2/humble/ros2.repos

接下来，使用vcs工具根据ros2.repos文件导入所有源码。这条命令会克隆数十个Git仓库，需要较长时间和稳定的网络。

vcs import src < ros2.repos

这里有一个巨大的坑：由于网络原因（特别是访问GitHub），这个命令很容易中途失败，报错某个仓库克隆超时。原始文章给出了一个很实用的技巧：如果某个仓库反复失败，你可以直接编辑ros2.repos文件，暂时注释掉除了这个失败仓库以外的所有其他仓库定义，然后再次执行vcs import命令。等这个难啃的仓库克隆成功后，再恢复文件，继续导入剩下的。虽然笨拙，但非常有效。你也可以考虑配置Git的代理或者使用国内镜像源来加速。

3.2 使用rosdep安装系统依赖

vcs import只获取了ROS2的源代码，这些代码还依赖许多我们之前可能没安装完的系统库。rosdep这个工具就是用来解决这个问题的。它能根据仓库中的package.xml文件，自动识别并安装所需的系统依赖。

首先，确保rosdep已安装并初始化。在Debian上，包名可能是python3-rosdep2。

sudo apt-get install -y python3-rosdep2
sudo rosdep init
rosdep update

rosdep init可能会因为网络问题失败，提示“找不到目标”。如果遇到，可以手动下载配置文件。但通常多试几次rosdep update就能成功。初始化完成后，在工作空间根目录运行：

cd ~/ros2_humble
rosdep install --from-paths src --ignore-src -y --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers"

这条命令是核心：

--from-paths src：告诉rosdep查看src目录下的所有包。
--ignore-src -y：自动忽略已从源码获取的包，并对所有安装提示回答“是”。
--skip-keys：跳过指定的键。这里跳过的fastcdr和rti-connext-dds-6.0.1是两种可选的DDS中间件实现，它们通常需要商业许可或特殊的安装步骤，我们暂时用不上。urdfdom_headers可能因为版本问题在Debian上安装失败，我们稍后手动处理。

执行这一步时，rosdep会再次尝试通过apt安装大量依赖。 请密切关注输出。如果遇到大量“无法定位软件包”的错误，不要灰心。这恰恰说明了我们之前手动安装依赖的必要性——rosdep是基于Ubuntu的数据库，对Debian的支持不完美。对于rosdep报告缺失的每一个包，你都需要回到第2.3节的策略：搜索、找替代、或决定是否真的需要（也许对应的ROS2包你可以选择不编译）。

4. 编译构建与疑难杂症攻坚战

经过漫长的准备，终于来到了编译阶段。这是最考验机器性能和耐心的环节，树莓派4B的4核Cortex-A72处理器在这时会全力运转。

4.1 启动编译与监控

在ros2_humble目录下，使用colcon工具启动编译。colcon是ROS2推荐的构建工具。

cd ~/ros2_humble
colcon build --symlink-install

--symlink-install参数意味着安装文件会以符号链接的方式指向构建目录，这样你修改源码后重新编译，无需重新“安装”，链接自动生效，方便开发。

编译过程会非常漫长，在树莓派4B上可能需要数小时。期间，CPU温度会升高，建议做好散热（一个小风扇很有用）。你可以打开另一个终端窗口，用htop命令监控CPU和内存使用情况。

4.2 常见编译错误与解决方案

编译几乎不可能一次通过。下面是我遇到的一些典型错误及解决方法：

错误1：内存不足（OOM Killer） 树莓派4B的内存（尤其是2GB或4GB版本）在并行编译大型包（如rviz2）时可能不够用。症状是编译进程突然被杀死。解决方法：

减少并行作业数：默认colcon会使用所有CPU核心。我们可以限制并行度，减少内存压力。
```
colcon build --symlink-install --parallel-workers 2 # 只用2个并行任务
```

增加交换空间（Swap）：在SD卡上划分一部分空间作为虚拟内存。注意这会增加SD卡磨损，但能有效防止OOM。

sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile # 修改CONF_SWAPSIZE=2048 (单位MB)
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

错误2：特定包编译失败（例如：rviz_default_plugins） 正如原始文章提到的，rviz_default_plugins这个包非常容易卡死或失败，因为它依赖复杂的图形库（Ogre, Qt）。解决方法：

单独编译：如果整体编译卡在这个包，可以跳过它，先编译其他。
```
colcon build --symlink-install --packages-skip rviz_default_plugins
```
后续单独处理：等其他包都编译成功后，再集中精力解决这个“钉子户”。可以尝试在系统资源相对空闲时，单独编译它，并打开更详细的日志。
```
colcon build --symlink-install --packages-select rviz_default_plugins --cmake-args -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON
```
从详细输出中寻找具体的错误行，往往是某个头文件找不到或链接库缺失。根据错误信息，回头检查对应系统库（如libogre-1.12-dev）是否安装正确。

错误3：找不到urdfdom_headers 这个包在Debian 12中可能名字不同或版本不兼容。如果rosdep跳过了它，但编译时又需要，我们可以手动安装或从源码编译。先尝试搜索：

apt search urdfdom | grep header

如果找不到，最可靠的方法是从ROS的ros2.repos文件里找到它的源码仓库（通常在src/urdf/urdfdom_headers），然后手动用CMake编译安装。或者，如果你的机器人项目暂时不需要URDF模型解析功能，可以在编译时通过--packages-skip跳过依赖它的包。

错误4：Python模块导入错误 编译过程中，一些Python脚本可能会运行，如果你的Python环境混乱（比如系统Python和用户Python混用，或者PYTHONPATH设置有问题），可能导致ImportError。确保你一直使用python3和pip3，并且在编译过程中不要随意切换环境。

4.3 增量编译与问题隔离

不要指望一次colcon build就能成功。更现实的流程是：启动编译 -> 遇到错误 -> 停止编译（Ctrl+C）-> 根据错误信息解决问题 -> 重新编译。colcon支持增量编译，只会重新编译发生变化的包及其依赖，这大大节省了时间。

解决问题的核心是阅读错误信息。编译错误信息通常很长，但关键信息一般在最后几行。把错误信息复制出来，去掉项目特有的路径名，直接去搜索引擎（如Google或百度）搜索，有很大概率能找到解决方案。ROS2社区非常活跃，很多坑已经有人踩过并分享了经验。

5. 系统集成、测试与优化建议

当编译最终成功完成，看到大大的“Summary: X packages finished”字样时，恭喜你，最艰难的部分已经过去了。接下来就是将ROS2集成到你的系统环境中，并验证它是否正常工作。

5.1 环境配置与基础功能测试

编译产物会安装在~/ros2_humble/install目录下。要让系统知道ROS2命令的存在，需要将其setup.bash脚本加入shell的启动配置中。

echo "source ~/ros2_humble/install/setup.bash" >> ~/.bashrc
source ~/.bashrc

现在，你可以测试ROS2的核心功能了。打开一个终端，运行经典的turtlesim模拟器节点：

ros2 run turtlesim turtlesim_node

如果一切顺利，你应该会看到一个带有随机小海龟的图形窗口（如果你安装了图形界面和必要的GUI库）。在另一个终端中，运行键盘控制节点：

ros2 run turtlesim turtle_teleop_key

在这个终端里按方向键，就能控制小海龟移动了。这个简单的测试验证了ROS2的核心通信机制（节点、话题）是正常的。

5.2 进阶测试与系统集成

通过turtlesim只是第一步。你可以进行更多测试来确保系统完整性：

检查DDS实现：ROS2默认使用Cyclone DDS或Fast DDS。运行ros2 doctor命令，它可以检查你的ROS2环境配置并报告潜在问题。
尝试其他示例：运行ros2 topic list查看当前活跃的话题，或者尝试其他演示包，如demo_nodes_cpp或demo_nodes_py。
与硬件集成：如果你有USB摄像头，可以尝试ros2 run image_tools cam2image来发布图像话题（需要先安装libopencv-dev并成功编译相关包）。

系统集成建议：

设置开机自启动：对于机器人应用，你可能希望某些ROS2节点在树莓派启动时自动运行。可以考虑使用systemd服务单元来实现。
优化性能：编译时，colcon的--cmake-args可以传递优化参数。例如，针对树莓派4B的ARM Cortex-A72架构，可以添加-DCMAKE_CXX_FLAGS="-O2 -mcpu=cortex-a72"来生成针对性优化的代码。
空间清理：编译完成后，build和log目录会占用大量空间（可能超过10GB）。如果你确认编译成功且暂时不需要调试，可以删除它们以释放SD卡空间：rm -rf ~/ros2_humble/build ~/ros2_humble/log。install和src目录必须保留。