拿到一块新的ARM开发板兴冲冲刷好Ubuntu 22.04按照网上的教程开始装ROS2 Humble结果从换源开始就一路踩坑装到深夜心态炸裂——这个场景我相信不少搞机器人、嵌入式的小伙伴都经历过。我最近在树莓派4B和一块RK3588的开发板上分别完整走了一遍ROS2 Humble的安装流程中间踩过的坑、绕过的弯路感觉值得整理成一份能直接照着抄的避坑指南。这篇文章围绕ARM架构下Ubuntu 22.04安装ROS2 Humble的完整链路展开重点解决三类问题一是系统层面的软件源配置与基础环境准备二是ROS2 Humble安装过程中ARM板特有的坑三是装完之后如何验证环境、规避后续开发的隐患。如果你用的是树莓派、香橙派、RK3588这类ARM开发板或者是在ARM云主机上折腾ROS2这篇文章应该能帮你省下好几个晚上的时间。1. 为什么是Ubuntu 22.04 ROS2 Humble ARM板这套组合1.1 版本匹配关系不是随便选的ROS2的版本和Ubuntu系统版本有严格的对应关系这一点和ROS1时期“一个ROS版本适配多个Ubuntu”的做法完全不同。ROS2 Humble Hawksbill是2022年5月发布的LTS版本官方支持期限到2027年它对应的操作系统是Ubuntu 22.04 Jammy。这个对应关系在ROS2的官方文档里写得很清楚但很多人装的时候会忽略这一点。如果你在Ubuntu 20.04上强行装Humble依赖关系会乱成一锅粥反过来在Ubuntu 24.04上装Humble虽然部分能用但官方并不保证所有功能正常因为24.04对应的ROS2版本是Jazzy。所以选择Ubuntu 22.04 ROS2 Humble并不是巧合而是ROS2版本迭代机制决定的。ARM开发板这块情况要复杂一些。树莓派4B用的是ARMv8-A架构的Cortex-A72属于64位ARM可以跑arm64版本的Ubuntu。RK3588同样支持arm64。这里有一个关键点ROS2官方对ARM架构的支持分为arm64和armhf前者是64位后者是32位。现在的开发板主流都是64位建议直接选择arm64版本的Ubuntu镜像性能和兼容性都更好。1.2 不同ARM开发板的选型差异我在树莓派4B8GB版和RK3588开发板上都实测过两者装ROS2 Humble的流程基本一致但有几个细微差别开发板处理器架构内存系统镜像注意事项ROS2安装体验树莓派4BARMv8-A (Cortex-A72)2/4/8GB建议官方Ubuntu Server 22.04.3 arm64可用但编译大包时偏慢树莓派5ARMv8-A (Cortex-A76)4/8GB官方已支持性能提升明显体验较好RK3588系列ARMv8.2-A (Cortex-A76A55)4~32GB各厂商镜像质量参差建议选纯净版性能充裕香橙派5系列ARMv8-A4/8/16GB注意区分32位和64位固件可用对于内存只有2GB的开发板装ros-humble-desktop会比较吃力建议选择ros-humble-ros-base后续缺什么包再单独补。内存4GB及以上的板子直接上desktop版本问题不大。1.3 为什么直接上ROS2而不是ROS1现在还有一些教程推荐装ROS1 Noetic但Noetic在2025年已经停止维护而且对于新项目来说ROS2的分布式通信、DDS中间件、生命周期节点等设计更符合现代机器人系统的需求。Humble作为ROS2的LTS版本社区积累的教程和资料已经相当丰富生态也逐渐成熟。如果你不是要复现一个老项目没必要从ROS1开始了。2. 系统准备阶段最容易翻车的三个细节2.1 ARM版Ubuntu镜像怎么选才不坑不管是树莓派还是RK3588选系统镜像都要留个心眼。树莓派推荐直接去Ubuntu官网下载选择Ubuntu Server 22.04.3 LTS (Jammy Jellyfish)的arm64版本格式是ubuntu-22.04.3-preinstalled-server-arm64raspi.img.xz用官方的Raspberry Pi Imager烧录就行。RK3588开发板的情况要复杂一些不同厂商提供的Ubuntu镜像差异很大。有的厂商镜像预装了一堆东西有的甚至不是标准Ubuntu而是基于Debian魔改的。这里我的建议是优先选厂商提供的“纯净版”Ubuntu 22.04镜像尽量不要选带桌面环境的一体化镜像。因为开发板上很多预装环境会和ROS2的依赖产生冲突到时候排查起来非常痛苦。烧录工具方面树莓派直接用Raspberry Pi Imager即可RK3588一般用balenaEtcher或者dd命令。烧录完成后首次开机建议连接显示器和键盘操作避免一上来就折腾SSH——ARM板的网络配置经常会出现一些奇怪的问题。2.2 换源之前先搞清楚架构apt源的arm64坑这是很多人忽略的问题。ARM开发板换源时必须使用支持arm64架构的软件源。阿里云、清华、中科大的Ubuntu源都支持arm64但在写sources.list的时候要注意格式。apt源地址里的$ARCH或者直接路径必须正确。Ubuntu 22.04的软件源配置文件是/etc/apt/sources.list从Ubuntu 22.04开始推荐使用.sources格式的DEB822源文件/etc/apt/sources.list.d/ubuntu.sources。我用阿里云源的操作是这样的sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo bash -c cat /etc/apt/sources.list EOF deb https://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse EOF但如果你用的是新版.sources文件格式则需要这样写sudo nano /etc/apt/sources.list.d/ubuntu.sources把其中的URIs字段改为https://mirrors.aliyun.com/ubuntu/即可。换源之后执行sudo apt update注意观察是否有Error提示。如果输出里出现Ign忽略或者404 Not Found通常是因为某些软件包在arm64架构下不存在这属于正常现象不影响核心安装。2.3 pip源、git源、以及hostname的网络问题换源不只是换apt源。安装ROS2过程中需要用到colcon等Python工具pip默认源在国内安装速度很慢建议一并换成阿里云pip源mkdir -p ~/.pip cat ~/.pip/pip.conf EOF [global] index-url https://mirrors.aliyun.com/pypi/simple/ timeout 120 EOFgit拉取ROS2源码时如果速度不理想可以考虑使用ghproxy等加速服务但注意Humble用apt方式安装其实不太需要走git拉源码除非你要编译特定的功能包。hostname方面ARM板装上系统后默认主机名可能是ubuntu或者厂商设定的名称。ROS2分布式通信依赖DDS而DDS对网络环境变化比较敏感。建议在装ROS2之前就把hostname改成有意义的名字比如ros2master并确保/etc/hosts中的解析正常sudo hostnamectl set-hostname ros2master echo 127.0.0.1 $(hostname) | sudo tee -a /etc/hosts如果这一步偷懒后面在多台开发板之间做ROS2分布式通信时经常会出现节点互相发现不了的情况排查起来会让人崩溃。3. ROS2 Humble安装全程记录与关键踩坑点3.1 官方推荐的安装方式apt比源码香ROS2的安装方式主要分两种apt二进制包安装和源码编译安装。对于ARM开发板我的强烈建议是用apt方式安装。原因很简单源码编译在ARM板上耗时太长ros-humble-desktop如果从源码编译在树莓派4B上可能要跑好几个小时甚至更久而且过程中容易因为内存不足被kill掉体验很差。apt安装方式的核心步骤在ROS2官方文档里有详细说明但有几个坑需要单独提示。3.2 设置locale时不要跳过官方文档的第一步是设置locale支持UTF-8sudo apt update sudo apt install -y locales sudo locale-gen en_US en_US.UTF-8 sudo update-locale LC_ALLen_US.UTF-8 LANGen_US.UTF-8 export LANGen_US.UTF-8很多教程说这一步可以跳过实际操作中发现如果locale设置不正确后续rosdep和colcon工具运行时会报一些奇怪的字符编码错误。所以这一步别偷懒一次执行到位。3.3 添加ROS2源阿里云ROS源的正确添加方式官方源的地址是https://packages.ros.org/ros2/ubuntu在国内访问偶尔会超时。这里可以换成阿里云的ROS2镜像源。首先安装必要的工具并添加ROS2 GPG Keysudo apt update sudo apt install -y curl gnupg lsb-release sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg这里有一个非常关键的坑raw.githubusercontent.com在国内经常无法直接访问导致curl这步失败。网上很多教程写到这一步就断了解决方案有几种方案一先想办法把ros.key文件下载到本地比如用代理或者从国内镜像获取然后手动放到位。如果你电脑上有这个文件用U盘拷贝过去也行。方案二使用清华大学或者中科大提供的ROS2镜像源中带的key文件。清华源的地址是https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu.key可以尝试sudo curl -sSL https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu.key -o /usr/share/keyrings/ros-archive-keyring.gpg拿到key之后添加软件源以阿里云为例echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.aliyun.com/ros2/ubuntu jammy main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null注意这个源地址是https://mirrors.aliyun.com/ros2/ubuntu不要和apt的https://mirrors.aliyun.com/ubuntu/搞混。添加完成后执行sudo apt update如果这一步能够正常获取到ROS2的包列表说明软件源配置成功。3.4 安装ROS2包桌面版还是基础版安装命令很简单但选什么包取决于你的需求和使用场景# 基础版不含GUI工具适合服务器或资源受限的板子 sudo apt install -y ros-humble-ros-base # 桌面版含rqt、rviz2等图形化工具推荐 sudo apt install -y ros-humble-desktop # 开发工具编译功能包时必备 sudo apt install -y ros-dev-tools这里补充说明一下ros-dev-tools它是一个元包会帮你装好colcon、rosdep、ament等一系列ROS2开发常用的命令行工具。如果不装这个后续自己创建功能包、编译工作空间的时候会缺很多东西。对于内存充足的开发板4GB及以上直接装ros-humble-desktop没错。2GB内存的板子建议先装ros-humble-ros-base因为你大概率跑不动rviz2装了反而吃内存。3.5 环境变量配置与自动加载安装完成后需要把ROS2的环境变量加载到shell中echo source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc这个步骤人人都会做但有一个高频错误如果你用的是zsh而不是bash这行要写入~/.zshrc。另外如果同时装了ROS1和ROS2环境变量会互相冲突建议在~/.bashrc中做条件判断。4. ARM板上独有的三个大坑内存、中间件、权限4.1 编译功能包时的OOM问题与swap配置ARM开发板相比x86 PC最大的弱势就是内存。我自己在树莓派4B上编译一些功能包时遇到最多的问题就是编译器被OOM Killer干掉终端直接提示Killed没有任何报错信息就像凭空消失了一样。排查和解决思路如下先看当前内存和swap情况free -h如果swap为0或者很小建议先扩容swap。创建一个4GB的swap文件对于树莓派4B够用了sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile echo /swapfile none swap sw 0 0 | sudo tee -a /etc/fstab同时降低编译时的并发度。很多人习惯用colcon build --parallel-workers 4来加速编译但ARM板上4个并发编译进程很容易把2GB内存吃满。我的建议是colcon build --parallel-workers 2或者让系统根据可用内存自动调整colcon build --parallel-workers $(nproc --ignore 1)另一个技巧是使用MAKEFLAGS环境变量控制Make的并发数export MAKEFLAGS-j2 colcon build这两个配合使用能有效降低OOM的发生概率。4.2 DDS中间件选型Fast-DDS还是CycloneDDSROS2的通信底层基于DDS默认使用的中间件实现是Eclipse CycloneDDSHumble版开始在某些平台上默认或者Fast-DDS具体看发行版配置。Humble默认推荐Fast-DDS但实际使用中两者在性能、资源占用、发现机制上各有差异。在性能较弱的ARM板子上Fast-DDS的资源占用偏高而且它的默认discovery机制通过多播发现节点在某些网络环境下会变得非常慢。如果你发现两个节点运行起来之后要等好几秒才能互相发现那问题大概率出在DDS的发现机制上。可以尝试把默认中间件切换为CycloneDDSsudo apt install -y ros-humble-rmw-cyclonedds-cpp echo export RMW_IMPLEMENTATIONrmw_cyclonedds_cpp ~/.bashrc source ~/.bashrcCycloneDDS在资源受限的嵌入式平台上通常表现更好启动发现速度更快。切换中间件之后记得重新运行你的节点测试确认通信正常。如果你要做多机通信还需要注意DDS发现域的问题。ROS2默认的domain ID是0多台设备在同一个局域网内如果都是一个ID那么节点之间会自动发现并通信。但如果网络环境存在多个子网或者有防火墙拦截了多播报文就需要手动指定网卡export ROS_AUTOMATIC_DISCOVERY_RANGELOCALHOST或者设置ROS_DOMAIN_ID避免跨设备干扰。这部分展开讲很深但作为安装后的头等注意事项值得先了解一下。4.3 用户组与设备权限串口、摄像头、GPIO开发板玩机器人必然要接串口、摄像头、雷达这些外设而Linux下访问这些设备需要对应的权限。把当前用户加入dialout组是ROS2嵌入式开发的惯用操作sudo usermod -aG dialout $USER sudo usermod -aG video $USER sudo usermod -aG i2c $USER sudo usermod -aG gpio $USER不同开发板用户组名称略有差异。树莓派上GPIO的组是gpioRK3588的厂商镜像有的用的是gpio有的直接root操作权限。加入用户组之后要重新登录或者重启才能生效这是很多人容易忽略的一个环节——加完组立刻执行ls /dev/ttyUSB0发现没有权限然后怀疑人生。还有一个小坑是很多ARM板的串口设备名不是ttyUSB0而是ttyS0或者ttyAMA0访问权限和性能表现都不一样。建议先执行ls /dev/tty*确认设备名再配置串口权限。5. 安装完成后的自检验证与常见错误处理5.1 用talker/listener快速自检装完之后我的习惯是第一步先跑官方自带的C和Python示例确认通信链路通畅source /opt/ros/humble/setup.bash ros2 run demo_nodes_cpp talker新开一个终端source /opt/ros/humble/setup.bash ros2 run demo_nodes_py listener如果talker在发送listener在接收基本可以确认ROS2的核心机制没毛病。如果listener收不到消息优先检查防火墙sudo ufw status如果防火墙是开启状态要么临时关闭不建议生产环境这么做要么放行对应端口。ROS2默认使用多播和动态端口最省事的做法是让DDS流量通过局域网网卡而不是简单地把防火墙关闭了事。5.2 排查工具ros2 doctor和日志如果出现问题ros2 doctor是一个很实用的诊断命令。它会对系统环境、软件包状态、网络配置做一次全面体检ros2 doctor --report这个命令会输出很多信息重点关注下面的System和ROS 2两部分。如果出现warning级别的提示大部分不影响使用但如果出现error级别的信息就需要逐一排查了。日志方面ROS2把运行日志默认存储在~/.ros/log/目录下。排查节点崩溃、莫名退出的问题去这个目录里找最新的log文件往往比盯着终端输出有效得多。5.3 创建第一个工作空间并编译一个功能包自检通过之后我建议再创建一个最小的C功能包完整走一遍编译流程确保colcon和ament工具链正常工作mkdir -p ~/ros2_ws/src cd ~/ros2_ws colcon build source install/setup.bash ros2 pkg create --build-type ament_cmake test_pkg --node-name test_node colcon build --packages-select test_pkg如果编译过程中报错Package test_pkg not found检查一下是否忘了source install/setup.bash。这个失误非常常见不管我自己还是身边朋友都跳过这个坑。还有一个ARM板上比较常见的报错是undefined reference to ...这通常跟编译器版本或者缺少某些依赖库有关。解决办法是先检查依赖是否装全rosdep install --from-paths src -y --ignore-src这个命令会自动分析src目录下所有功能包的依赖并尝试通过apt安装缺失的库。注意第一次运行rosdep需要先初始化sudo rosdep init rosdep update如果rosdep update因为网络问题失败可以考虑添加代理或者通过手动修改rosdep源的方式处理。6. 把安装过程固化成脚本以后刷机不怕重装6.1 为什么建议写一个安装脚本ARM开发板的好处是便宜坏处是经不起折腾——系统刷坏了就重来一遍重装一次ROS2的代价可不小。我第一次在RK3588上手动安装ROS2时花了大半天第二次花了两个小时第三次我已经可以在二十分钟内完成全新环境的搭设。把安装过程固化成脚本本质上是在编写“环境即代码”。下次换新板子或者系统被搞坏执行一下脚本就能恢复到熟悉的ROS2环境节省的时间相当可观。6.2 我自己的安装脚本简化版下面这个脚本我实测过在树莓派4B和RK3588上都能用关键是它把前面提到的坑都绕开了#!/bin/bash set -e # 检查架构 ARCH$(uname -m) if [ $ARCH ! aarch64 ]; then echo 当前架构为 $ARCH本脚本仅支持aarch64arm64 exit 1 fi # 1. 设置locale sudo apt update sudo apt install -y locales sudo locale-gen en_US en_US.UTF-8 sudo update-locale LC_ALLen_US.UTF-8 LANGen_US.UTF-8 # 2. 换apt源为阿里云 sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo bash -c cat /etc/apt/sources.list EOF deb https://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse EOF # 3. 添加ROS2源使用清华的key sudo apt update sudo apt install -y curl gnupg lsb-release sudo curl -sSL https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu.key -o /usr/share/keyrings/ros-archive-keyring.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.aliyun.com/ros2/ubuntu jammy main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null # 4. 安装ROS2 sudo apt update sudo apt install -y ros-humble-desktop ros-dev-tools # 5. 配置环境变量 echo source /opt/ros/humble/setup.bash ~/.bashrc source /opt/ros/humble/setup.bash # 6. 换pip源 mkdir -p ~/.pip cat ~/.pip/pip.conf EOF [global] index-url https://mirrors.aliyun.com/pypi/simple/ timeout 120 EOF # 7. 配置用户组需重新登录后生效 sudo usermod -aG dialout $USER sudo usermod -aG video $USER echo ROS2 Humble 安装完成请重新登录系统使用。这里有几个细节值得说明脚本最后加了set -e任何一步出错立即退出方便定位问题key文件的获取用的是清华源因为这个域名在国内访问比raw.githubusercontent.com稳定得多软件源用的是阿里云ROS2镜像实测速度和稳定性都不错用户组配置完成后不会立即生效脚本会提示重新登录避免用户误以为已经生效。6.3 脚本化安装的后续维护有了脚本之后还有一个很值得做的事用git管理你的脚本和配置文件。ARM开发板上面做机器人开发配置文件的版本管理同样很重要。我的做法是在PC上建立一个ros2-arm-setup仓库把安装脚本、.bashrc自定义配置、DDS配置文件等放进去。每次修改配置后提交并推送。新板子到手后先执行安装脚本再拉取配置文件覆盖十分钟就能恢复到开发状态。DDS配置文件也要单独说一下。如果你像我一样需要频繁在ARM板上调整中间件参数建议把cyclonedds.xml放进仓库启用时用环境变量指定export CYCLONEDDS_URIfile://$HOME/cyclonedds.xml这个配置文件可以控制发送缓冲区大小、网络接口、发现超时时间等参数对嵌入式场景非常有帮助。最后再分享一个小技巧在ARM板上跑完安装脚本之后登录到系统里会看到终端输出reboot的提示。别急着立刻重启先把~/.bashrc里的内容单独打开看一眼确认source /opt/ros/humble/setup.bash这行真的写进去了。我遇到过脚本执行成功但bashrc没写入的情况排查半天发现是脚本里的重定向符号被转义错了。顺手检查一下能帮你省掉重启后发现环境变量没加载的尴尬。