ARM开发板安装ROS2 Humble指南：换源、配置与避坑全记录

这段时间帮朋友在一台ARM开发板上从零折腾ROS2 Humble整个过程可以说是把能踩的坑基本都踩了一遍。板子用的是RK3588方案的国产开发板系统是Ubuntu 22.04arm64目标就是装一个能跑起来、能建图导航、能正常通信的ROS2 Humble环境。中间经历了换源失败、公钥报错、rosdep超时、节点起不来、rviz2卡成PPT等一系列问题。这篇文章就把完整的安装流程和避坑记录整理出来给准备在ARM开发板上入坑ROS2的同学当个参考手册。先说清楚这文章不是把ROS2官方文档翻译一遍而是结合ARM板这些资源受限设备的真实情况把软件源怎么换、ROS2怎么装、环境怎么配、遇到报错怎么排查这些事讲透。内容同样适用于香橙派、树莓派、Jetson系列只要是arm64架构的Ubuntu 22.04思路基本一致只有个别细节差异。1. 动手之前先搞懂这套组合的脾气1.1 ARM板上的Ubuntu 22.04到底特殊在哪很多人刚开始用ARM开发板装东西最容易忽略的一件事就是ARM版的Ubuntu和x86版的Ubuntu虽然界面长得一样、命令用起来一样但底层的软件源是完全不同的。x86用的是archive.ubuntu.com那一套源ARM架构用的是ports.ubuntu.com。如果你在ARM板上直接抄x86电脑上的换源教程把源地址换成mirrors.aliyun.com/ubuntu/系统在apt update的时候就会报一堆404错提示找不到Release文件最后什么包都装不了。另外ARM架构还要分清楚arm64和armhf。像RK3588、树莓派4B以上、Jetson系列这些都是64位的arm64架构这也是ROS2 Humble官方支持的架构。armhf属于32位Ubuntu 22.04对armhf的支持已经缩水了ROS2也基本不理会这种平台。所以开始操作之前先确认一下自己的板子架构uname -m dpkg --print-architecture如果输出是aarch64和arm64就是标准的arm64环境后面所有步骤可以放心照着做。还有一个很实际的问题ARM开发板的存储空间普遍吃紧。很多板子用的是16GB、32GB的eMMC或者TF卡装完系统桌面版之后可用空间可能只剩几个GB这在安装ROS2 Humble的时候会非常被动。因为ros-humble-desktop完整版安装完之后光/opt/ros目录就要吃掉将近2GB加上编译依赖和缓存整体空间需求大概在4GB到6GB。所以动手之前我强烈建议先看看磁盘余量不够的话先扩容或者把不用的包清理一遍或者给ROS2加上--no-install-recommends参数减少依赖体积后面安装环节会详细讲。1.2 ROS2 Humble为什么值得在ARM上折腾ROS2 Humble Hawksbill是ROS2的LTS版本官方支持周期到2027年对应的Ubuntu版本就是22.04Jammy。对于要在嵌入式设备上做长期项目的人来说LTS意味着不会用着用着就被版本更新割裂社区支持和软件包兼容性都更稳。和ROS1的Kinetic、Noetic相比ROS2从架构上就不依赖roscore中心节点采用了基于DDS的分布式通信每个节点独立运行单点故障不会拖垮整个网络这对多机协作、机器人集群控制来说是刚需。在ARM开发板上使用ROS2还有一个特别合拍的原因ROS2对资源占用是可控的。跟ROS1那种必须开一个roscore常驻进程的架构不同ROS2节点是去中心化的如果你把内置的DDS后端换掉比如用Cyclone DDS替代默认的Fast DDS内存占用能下降一半以上。这就让资源本来就不多的ARM板子有了更多余量去跑感知、导航这些重负载节点。我之前也见过不少人在树莓派上折腾ROS1 Noetic费了半天劲把环境搭好了结果发现很多新出的功能包、算法包已经不给ROS1开发版本了生态迁移已经是大势所趋。既然2023年之后社区的主流资源都涌向ROS2那在ARM板上直接一步到位装Humble反而是省时间的选择。这篇文章后面的所有步骤也都是基于ROS2 Humble在arm64 Ubuntu 22.04上的环境来展开的。2. 阿里云换源ARM板的第一步也是第一道坎2.1 新版Ubuntu的源写法变了很多换源教程讲的是Ubuntu 20.04或者更早版本的做法直接编辑/etc/apt/sources.list文件就行了。但Ubuntu 22.04改用了DEB822格式的源配置默认的软件源配置移到了/etc/apt/sources.list.d/ubuntu.sources这个文件里/etc/apt/sources.list反而变成了一个空文件或者不存在。当时有个朋友拿着旧教程去改/etc/apt/sources.list写进去之后发现apt update一点反应都没有白白浪费了半小时。所以ARM板上换源的第一步是先看清楚系统默认的源配置放在哪个文件。22.04系统里正确的操作对象是/etc/apt/sources.list.d/ubuntu.sources它的内容结构大概是这样Types: deb URIs: http://ports.ubuntu.com/ubuntu-ports/ Suites: jammy jammy-updates jammy-backports Components: main universe restricted multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg注意这个URIs字段默认就是ports.ubuntu.com因为这是给非x86架构用的端口。换源的核心就是把ports.ubuntu.com替换成阿里云的镜像地址其他字段保留。2.2 阿里云源配置实操阿里云镜像站对Ubuntu ARM架构提供了专门的镜像路径地址是https://mirrors.aliyun.com/ubuntu-ports/。注意后面这个ubuntu-ports很多人写成了/ubuntu/结果又是一堆404。我个人的操作建议是不要直接用sed替换源文件而是一次性重写整个ubuntu.sources这样最干净不会残留旧源导致校验出问题。操作步骤sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak sudo tee /etc/apt/sources.list.d/ubuntu.sources EOF Types: deb URIs: https://mirrors.aliyun.com/ubuntu-ports/ Suites: jammy jammy-updates jammy-backbones Components: main universe restricted multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg EOF这里有个需要注意的细节写完之后Components这几个参数建议保留main universe restricted multiverse四个组件不要图省事只写main否则后面装ROS2依赖的时候会提示找不到一些软件包比如python3-vcstool、python3-colcon-common-extensions这些工具在universe组件里才有。编辑完源之后执行sudo apt update这一步如果看到正常滚动出软件包索引信息没有404和无法连接的错误说明阿里云源已经生效。顺手再执行一次sudo apt full-upgrade -yARM开发板很多出厂系统是旧版本的内核和固件升级一遍能避免后面不少奇奇怪怪的编译问题。不过升级时间可能在几分钟到十几分钟不等取决于板子和网络速度耐心等即可。2.3 换源后必做的完整性检查换完源别急着就开始装ROS2先用几条命令确认一下系统状态不然装到一半出了问题排查起来特别费劲。# 检查系统版本和架构 lsb_release -a dpkg --print-architecture # 检查关键工具是否存在 which curl which gnupg which lsb_release如果curl或者gnupg没装先补上sudo apt install -y curl gnupg lsb-release这两个工具后面添加ROS2公钥的时候必须用到。另外如果板子还没有装software-properties-common建议也一起装掉它提供了一些apt扩展功能后续装第三方源和开发工具能省不少事。磁盘空间这块也再强调一次。查看空间df -h如果/分区的可用空间少于5GB建议先处理。我见过有人硬着头皮装到最后系统提示/opt/ros写入失败然后整个apt状态锁住清理起来很麻烦。空间不够的话有几个办法清理/var/cache/apt/archives下的缓存包、删除不用的桌面软件、挂载外置U盘或NVMe硬盘把/opt/ros软链过去。不过最省心的还是在开始之前就把空间准备出来。3. ROS2 Humble安装全流程记录3.1 基础环境准备locale和开发工具ROS2对系统的locale有要求需要支持UTF-8编码。如果当前系统locale设置不对编译和运行阶段会报一些Perl警告或者编码错误。检查现在的localelocale如果显示的语言不是en_US.UTF-8或者zh_CN.UTF-8这种带UTF-8后缀的建议统一改成UTF-8环境。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 export LANGen_US.UTF-8很多人在这一步图省事想保留中文locale实测下来也能用但后续在编译一些英文注释比较多的包时偶尔会遇到编码相关的警告所以还是推荐切到UTF-8的英文环境纯粹是为了减少麻烦。接下来安装一些基础编译工具和版本管理工具ROS2工作空间编译时会用到sudo apt install -y git cmake build-essential python3-pip python3-venv3.2 添加ROS2软件源和公钥ROS2官方apt源地址是packages.ros.org这个源对国内的网络并不总是友好但因为在软件包解析阶段ROS2源里的包本体数据量不算大所以只要公钥能顺利添加后面下载安装包的速度还是可以接受的。如果觉得官方源下载慢后续可以去阿里云镜像站找有没有对应的ROS2源镜像不过官方源稳定性优先建议先按官方路径来。添加ROS2 apt仓库的公钥sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg这里有一个高频报错点raw.githubusercontent.com在国内访问不稳定经常超时或者断流导致下载下来的ros.key文件是空的或者不完整后面执行apt update的时候就会报公钥错误。如果出现这种情况多试几次或者换一个能正常访问该文件的网络环境。我当时就遇到了三次超时第四次才成功文件大小正常是几千字节如果下载下来只有几百字节甚至0字节删掉重新下载。公钥下载好之后添加源列表。注意archarm64这个参数保证apt只搜索arm64架构的包echo deb [archarm64 signed-by/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu jammy main | sudo tee /etc/apt/sources.list.d/ros2.list执行完成后刷新源sudo apt update如果看到packages.ros.org的源正常加载说明ROS2源已经就位。3.3 选对安装包desktop版还是base版ROS2 Humble官方提供两种安装方式ros-humble-desktop和ros-humble-ros-base。前者包含机器人开发常用的GUI工具、仿真相关组件、可视化工具rviz2、demo例程等体积大、依赖多后者只包含通信、消息、基础库这些核心模块体积小很多。在ARM开发板上怎么选我的建议是分两种情况。如果板子是树莓派4B或者更低配置内存4GB以下、没有独立GPU硬上desktop版纯属折磨自己rviz2都带不动老老实实装ros-base然后在需要的时候再单独安装个别工具包。如果板子是RK3588、Jetson Orin这类性能不错的平台内存8GB以上可以装desktop版但也要有心理准备rviz2能跑但别指望太流畅。我这次在RK3588板子上选择的是ros-base加按需安装的方式。用ros-base打底加装rviz2、demo_nodes_cpp、turtlesim这些必要的演示和调试工具比全量desktop版省了将近1GB的磁盘空间。执行安装sudo apt install -y ros-humble-ros-base如果确定要完整版sudo apt install -y ros-humble-desktop安装过程长不长取决于板子和网络。我实测在RK3588上装ros-base大约需要10分钟desktop版大约需要20到30分钟。如果中途出现断网导致apt安装中断执行sudo apt --fix-broken install修复一下再重新装。3.4 初始化rosdep和环境变量rosdep是ROS2用来解析和管理依赖包的工具很多从源码编译的功能包在编译前都会调用rosdep install来检查依赖。所以这一步虽然不会影响ROS2本身跑demo但后续要编译自己的功能包时必须用到。安装rosdepsudo apt install -y python3-rosdep sudo rosdep init rosdep update这里踩坑率极高。sudo rosdep init需要访问raw.githubusercontent.com上的rosdistro文件网络不通的情况下会直接卡住或者报错。我碰到的错误信息大致是ERROR: cannot download from ...。如果遇到这种情况有几个思路可以尝试但总体原则是确保能够访问到这个文件。当时我是在网络状态比较好的环境里先把整个rosdistro仓库的关键文件下载到本地再用本地文件路径来初始化rosdep。官方文档也有类似的操作说明但流程比较繁琐。对多数人来说更实际的办法是直接调整hosts文件把相关域名的解析指到可访问的IP。不过这个做法需要你自己确认IP有效性不同网络环境下结果可能不一样。考虑到ROS2官方文档的安装指引可能会更新如果rosdep init一直失败最省事的方案是暂时跳过rosdep初始化先把ROS2环境跑起来。因为ros-base和desktop包安装完核心功能已经完全可用了rosdep只是在源码编译时才必须后续等网络条件好了再回来补。环境变量这一步很关键每次打开新的终端都执行一遍会觉得烦所以直接写入.bashrcecho source /opt/ros/humble/setup.bash ~/.bashrc echo export ROS_DOMAIN_ID1 ~/.bashrc source ~/.bashrcROS_DOMAIN_ID的取值范围是0到101它是用来隔离同一网络里多组ROS2设备的通信域。如果你在做多机通信不同机器人要设置不同的domain ID否则发出来的话题会互相干扰。单机调试用默认的0就行但为了以后扩展方便我习惯显式设置。再安装两个常用工具编译工作空间和命令行自动补全sudo apt install -y python3-colcon-common-extensions python3-argcomplete安装argcomplete之后记得执行sudo activate-global-python-argcomplete这样按Tab键自动补全就能生效操作效率会高很多。验证基础环境是否正常开两个终端一个跑talker一个跑listener# 终端1 ros2 run demo_nodes_cpp talker # 终端2 ros2 run demo_nodes_cpp listener如果listener终端不断打印I heard: [Hello World: ...]说明ROS2的核心通信链路已经打通整个环境基本可用了。4. 让ROS2跑得稳的环境细节4.1 补充开发工具colcon和VCS编译ROS2工作空间用的主要工具就是colcon。在ARM板子上用colcon编译功能包时如果包比较多建议限制并行编译任务数不然内存不够会导致编译器被系统杀死。比如编译时用colcon build --parallel-workers 2这是平时不太会注意但很实用的参数。在8GB内存的板子上开默认的并行任务编译一些大包时内存轻松冲到6GB以上随时可能卡死。限制成两个worker之后编译时间稍微长一点但稳定性提升很明显。除了colconvcs工具也建议装它用来管理多个Git仓库的代码版本很多从GitHub上拉取的ROS2功能包都通过.repos文件来批量下载sudo apt install -y python3-vcstool有了vcs后续想把Navigation2、Cartographer这些功能包源码拉到工作空间一条命令就能搞定不用一个个Git clone。4.2 DDS选型与多机通信的坑ROS2架构中DDS负责节点之间的数据传输。Humble默认使用Fast DDS在x86桌面环境下跑没有问题但在ARM板上Fast DDS的内存占用偏高。如果板子内存只有4GB跑个导航加视觉识别Fast DDS很容易把内存吃满然后节点莫名僵死。一个很有效的优化方案是把RMW实现切换为Cyclone DDS。Cyclone DDS在嵌入式设备上的内存占用明显低于Fast DDS而且对多机通信的兼容性也不错。切换方式sudo apt install -y ros-humble-rmw-cyclonedds-cpp echo export RMW_IMPLEMENTATIONrmw_cyclonedds_cpp ~/.bashrc source ~/.bashrc切换之后再跑ros2 run demo_nodes_cpp talker用htop看一下进程内存实测从Fast DDS的100MB多降到Cyclone DDS的40MB左右。对于运行多个节点的ARM板来说这个优化效果非常明显强烈推荐。多机通信方面不同ROS2设备要能互相发现和通信需要满足三个条件同一个网段、同一个ROS_DOMAIN_ID、防火墙开放DDS组播端口。很多人在多机模式下发现节点互相发现不了先检查这三项大概率就是某一项没满足。尤其注意板子的防火墙UFW默认开启的情况下需要用sudo ufw allow 7401/udp之类的命令放行DDS使用的端口段才能正常组网通信。4.3 rviz2和可视化工具在ARM板上的取舍ROS生态里最常用的可视化工具是rviz2但桌面版在ARM开发板上的渲染性能确实一般。RK3588有GPU结合硬件加速勉强能跑树莓派4B上开rviz2基本就是PPT效果旋转视角一卡一卡的。如果不是必须在板子上直接看可视化界面我推荐的方案是把可视化放到电脑端。板子上只跑ROS2的节点通过局域网把话题数据共享给电脑电脑上用rviz2连接查看。这样板子性能全用在节点计算上可视化交给电脑体验好很多。具体操作很简单板子上正常设置ROS_DOMAIN_ID和DDS类型电脑端安装相同版本的ROS2设置相同的domain ID然后在电脑上直接运行rviz2选择要显示的topic即可。如果跨网段就需要配置DDS的发现服务不过家用路由器场景下同一网段就够了不需要额外配置。如果板子上确实需要轻量化可视化可以试试Foxglove Studioweb版或者Webviz这两个工具通过浏览器展示板子上跑一个轻量服务电脑浏览器访问也能看话题数据和服务状态。我在调导航时用过Foxglove流畅度比板载rviz2好很多适合资源紧张的场景。5. 高频报错排查速查表5.1 apt源相关的报错和处理ARM板上换源后最容易遇到的报错是404 Not Found [IP: ...]。这个报错基本可以判定是源地址写错了。对照一下aaarch64架构一定要用ubuntu-ports路径千万不要用/ubuntu/另外确认系统版本号是jammy如果你用的是Ubuntu 22.04但源里写成focal同样会404。还常见一个问题更新源时提示The following signatures couldnt be verified because the public key is not available。这是公钥问题一般来说重新获取ROS2的ros.key文件可以解决注意获取后确认文件大小正常然后执行sudo apt update。如果还是报错手动检查/etc/apt/sources.list.d/ros2.list文件里的signed-by路径是否和实际存放公钥的位置一致。另一个坑是apt源更新后没生效检查有没有多个源文件冲突。如果你之前手动创建过/etc/apt/sources.list的文件并且里面写了旧源同时/etc/apt/sources.list.d/ubuntu.sources又是新写的apt会混着两个文件一起用容易出问题。建议只保留一个活跃的源配置文件。5.2 安装ROS2过程中的常见障碍安装ros2包时提示Unable to locate package ros-humble-ros-base先确认是否执行过sudo apt update然后确认源列表里是否已经有packages.ros.org的源记录。可以在/etc/apt/sources.list.d/下用ls看有没有ros2.list文件没有的话回到前文添加源的步骤。安装时提示某个依赖包version not found可能是阿里云源和ROS2源的更新不同步导致的一般执行sudo apt full-upgrade把系统包全部升级到最新再重试可以解决。还有一种情况是安装到一半中断apt锁被占用。解决方法是杀掉apt进程然后执行sudo rm /var/lib/dpkg/lock-frontend sudo dpkg --configure -a sudo apt --fix-broken install强制解锁之后重新执行安装命令。5.3 rosdep初始化和运行时问题排查rosdep初始化失败基本集中在网络访问问题上。查询rosdep状态rosdep check --include-eol-distros如果卡在update阶段可以先跳过。真正需要rosdep的时候是编译功能包之前到时网络条件允许再执行也一样。另外rosdep安装python包时如果提示pip源慢可以临时切换pip源pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/节点运行不起来ros2 run之后一直卡住或者报段错误排查思路先分三步第一步确认两个终端的ROS_DOMAIN_ID一致第二步确认RMW类型一致板子和电脑通信时必须用同一个DDS后端比如都切到Cyclone DDS第三步检查共享内存某些DDS需要在/dev/shm下有足够空间ARM板上默认共享内存只有系统内存的一半如果内存吃紧可以尝试重启板子清理这些临时文件。我在实际调试中还遇到过一次很隐蔽的问题板子的TF卡使用时间长了导致I/O性能严重下降同一块板子同样的安装流程TF卡上跑ros2 run明显卡顿换到NVMe硬盘或者新卡之后流畅了很多。所以如果板子突然变卡可以先查iostat和dmesg看I/O有没有异常。ARM开发板的外部存储性能和稳定性确实会影响ROS2这种实时性要求较高的系统。5.4 性能不够时还能做什么如果你在ARM板上跑ROS2感觉内存和CPU都不够用优先切换Cyclone DDS然后尽量减少不必要的节点数量尽量合并节点功能减少大量小消息的发布频率。编译优化上使用colcon build时加--cmake-args -DCMAKE_BUILD_TYPERelease可以提升编译后程序的运行效率。另外对于导航和建图这类计算密集的任务可以考虑使用板子上的NPU或者GPU做一些感知加速但这就超出安装范畴了后续如果有精力可以单独写一篇在RK3588上做ROS2感知加速的实践。还有一个小技巧是给系统增加swap空间。ARM板物理内存不够时swap能兜底防止OOM杀进程。创建一个4GB的swap文件sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile注意swap文件不要放在TF卡这种闪存介质上磨损严重而且读写性能不够。有条件的情况下优先放在NVMe或者SSD上。如果板子只有TF卡swap只做兜底用不要把它当成常规扩容方案。这个环境我在实际跑Navigation2和Cartographer的时候已经验证过稳定性板子上挂了四个节点加一个底盘驱动CPU占用在60%左右内存占用控制在2GB以内切换Cyclone DDS之后。后续准备继续在这块板子上做激光雷达建图和自主导航的适配测试到时候有新的坑再来继续更新。ARM开发板玩ROS2虽然起步阶段折腾但只要能熬过换源、装环境、调DDS这几道坎后面会越来越顺。