搞过Ubuntu的人应该都有同感系统装好了、显卡驱动怼上了、开发环境折腾妥了最怕看到的就是终端里冒出一行Command ros2 not found。ROS2的安装说难不难但网上教程参差不齐有的让你直接apt install ros-humble-desktop结果源没配好报一排错有的让你源码编译一编就是三四个小时最后还经常挂在某个依赖上。我这次在Ubuntu 22.04上完整走了一遍ROS2 humble的安装流程从系统准备、软件源配置、正式安装到colcon工作区搭建和小乌龟验证每一步都记录了下来。这篇文章既写给第一次接触ROS2的初学者也给那些之前被Unable to locate package之类错误劝退的人做个完整排雷参考。先说明我的测试环境项目配置系统版本Ubuntu 22.04.3 LTS虚拟机与物理机均验证目标ROS版本ROS2 Humble Hawksbill安装方式apt二进制包安装非源码编译桌面环境GNOME 42默认ROS2 humble对应的是Ubuntu 22.04Jammy这个版本是目前LTS里用户基数最大的组合之一官方支持周期到2027年5月所以拿来作为学习和项目落地的主力版本都很合适。1. 为什么选humble版本对应关系与支持周期的底层逻辑在动手敲命令之前我建议你先花两分钟搞清楚一个事情——为什么偏偏是humble而不是更新的jazzy或者更早的foxy。ROS2的每个发行版和Ubuntu版本之间有严格的对应关系不是随便一个ROS版本都能装在你的系统上的。官方发布策略是每个ROS2版本对应固定的Ubuntu发行版这个对应关系由二进制包的编译环境决定跨版本安装轻则缺依赖重则根本装不上。1.1 版本代号与Ubuntu版本的对应规则ROS2的命名规则是代号加海龟品种humble的全称是Humble Hawksbill肯氏丽龟它的目标平台是Ubuntu 22.04 Jammy。几个常用版本的对应关系如下ROS2版本对应Ubuntu版本支持状态Foxy FitzroyUbuntu 20.04 Focal已停止维护Humble HawksbillUbuntu 22.04 Jammy维护中至2027年Iron IrwiniUbuntu 22.04 Jammy已停止维护Jazzy JaliscoUbuntu 24.04 Noble维护中从表格能看出来如果你用的是Ubuntu 22.04长期维护的选项其实只有humbleIron已经停止维护Jazzy需要Ubuntu 24.04。网上有些教程会教你在22.04上装jazzy那种做法需要手动改源和绕过依赖检查即便装上了也容易在后续使用中出现ABI不兼容的诡异问题不建议新手尝试。1.2 支持周期与长期维护的取舍humble之所以被广泛使用还有一个现实原因它是ROS2第一个真正意义上的LTS版本。官方承诺的安全更新和维护周期到2027年这意味着你用它开发的项目、安装的第三方包、你发的论文用的代码在几年内都能在稳定的环境上运行不需要频繁跟着版本升级迁移。我个人的经验是除非你有明确需求必须用新版本的特性比如jazzy里的一些新API、新的通信机制否则在22.04上老老实实用humble就是最优解。官方文档、开源仓库、Stack Overflow上的问题讨论绝大多数都基于humble环境遇到问题搜到的解决方案也最全。2. 安装前准备换源、语言环境、依赖包三件事很多教程上来就让你添加ROS2的apt源然后直接开装忽略了一件事面向国内网络环境的软件源优化。如果你和我一样在国内网络环境下操作尤其是用虚拟机的时候这一步做不好后面会浪费大量时间在无意义的等待上。2.1 系统源切换与软件包更新打开终端首先要做的是备份现有的软件源文件这是改任何系统配置前的基本素养sudo cp /etc/apt/sources.list /etc/apt/sources.list.bakUbuntu 22.04的软件源文件用的是新的DEB822格式sources.list里只剩下一行引用实际源配置在/etc/apt/sources.list.d/ubuntu.sources这个文件里。你没必要手动去编辑这个文件直接用软件更新器或者sed替换镜像源就行但更推荐的方式是安装software-properties-common后用命令切换sudo apt update sudo apt install software-properties-common然后我用的是清华镜像源因为实测它的同步频率和速度都比较均衡。编辑/etc/apt/sources.list.d/ubuntu.sources把URIs: http://archive.ubuntu.com/ubuntu替换为URIs: https://mirrors.tuna.tsinghua.edu.cn/ubuntu即可。替换完成后执行sudo apt update sudo apt upgrade -y这一步把系统自带的软件包全部更新到最新状态能避免后面安装ROS2时因为某个底层库版本过旧导致的依赖冲突。2.2 设置UTF-8语言环境关键但容易被忽略为什么教程里都会提到locale设置因为ROS2的底层通信库尤其是rviz2和gazebo这类GUI工具对locale非常敏感非UTF-8环境下启动时经常出现乱码或者直接闪退。如果系统安装时选择了中文locale默认可能是zh_CN.UTF-8或en_US.UTF-8。检查当前设置locale我建议统一设置为en_US.UTF-8虽然中文环境也能用但ROS2的一些日志输出和工具链在英文环境下兼容性最好sudo apt install 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设置完成后需要重启终端或者重新登录会话才会完全生效。这个步骤不是必选项如果卡在这一步会浪费时间可以跳过但如果你后面装完启动rviz2时报错回来检查一下locale大概率能找到问题。2.3 launchpad密钥与certificates依赖ROS2的软件包是从packages.ros.org仓库拉取的这个仓库使用GPG密钥对软件包签名进行校验安装前必须把公钥添加到系统的信任列表中。这个环节最容易出问题的点是curl和gnupg没装导致密钥下载或者导入失败sudo apt install curl gnupg2 lsb-releaselsb-release用于识别当前系统的版本代号curl负责下载密钥文件gnupg2负责密钥的导入和管理。这三个工具都不大但缺一个就卡住。3. 三步配置ROS2软件源与密钥导入这一节是整篇安装流程的重头戏80%的安装失败都发生在这里所以我会把每一步的命令、预期输出和可能遇到的报错都写清楚。3.1 添加ROS2 apt源的完整命令首先将官方ROS2仓库的密钥添加到系统信任的keyring中sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg这条命令可以直接执行因为在安装ROS2之前/usr/share/keyrings目录是已经存在的Ubuntu系统自带不需要额外创建。它做的事情是用curl下载ROS官方的GPG公钥然后存入系统keyrings目录后续apt校验所有来自packages.ros.org的软件包时都会用这个公钥验证签名。然后添加仓库地址到apt源列表echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null我把这条命令拆开解释一下$(dpkg --print-architecture)动态获取当前系统架构一般是amd64避免写死signed-by/usr/share/keyrings/ros-archive-keyring.gpg指定apt使用我们刚下载的密钥去验证仓库签名这是新版apt要求的写法$(lsb_release -cs)动态获取系统代号Ubuntu 22.04会返回jammytee /etc/apt/sources.list.d/ros2.list把拼接好的仓库配置写入新文件执行完成后可以用下面的命令查看写入结果cat /etc/apt/sources.list.d/ros2.list预期输出deb [archamd64 signed-by/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu jammy main3.2 校验密钥导入是否成功很多教程在这一步直接让你apt update但如果你在国内网络环境下直连packages.ros.org这个仓库的访问速度通常不太乐观apt update可能会卡很久甚至直接超时。我建议添加完源之后先做一次轻量化验证ls -l /usr/share/keyrings/ros-archive-keyring.gpg确认文件存在且大小不为0。文件大概在几千字节级别如果显示大小为0说明刚才的curl下载失败了需要重新执行。然后执行sudo apt update如果看到类似Get:14 http://packages.ros.org/ros2/ubuntu jammy InRelease [4,561 B]的输出说明ROS2仓库连接正常密钥认证通过。如果报错信息包含The following signatures couldnt be verified说明密钥文件有问题回到上一步重新下载。3.3 常见源配置错误的排查我见过最多的问题是这两类第一类curl: (7) Failed to connect to raw.githubusercontent.com这是网络访问问题。raw.githubusercontent.com在国内的连通性不稳定如果curl下载不到密钥文件可以改用我实测可用的国内镜像地址sudo curl -sSL https://mirror.ghproxy.com/https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg或者用wget加上代理参数重试。如果公司网络有代理记得先给curl配置代理环境变量。第二类E: The repository http://packages.ros.org/ros2/ubuntu jammy Release does not have a Release file这个报错看起来像是仓库地址不对但实际上是你的系统代号识别出了问题。用lsb_release -cs检查输出是不是jammy如果不是说明lsb-release工具没装好或者系统信息文件有问题。直接手动把jammy写死也行echo deb [arch$(dpkg --print-architecture) 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 /dev/null4. 正式安装humble桌面版组件拆解与安装过程说明源配置好了接下来就是安装环节。这一步我会把版本选择的逻辑和每个组件的用途都讲清楚方便你按需取舍。4.1 按需选择desktop或base版本ROS2 humble提供了几个不同的包组合最常用的是这两个包名包含内容适用场景ros-humble-desktop核心通信库、turtlesim、rviz2、gazebo、demo节点、可视化工具等学习、开发、调试推荐ros-humble-base仅核心通信库、命令行工具、生命周期管理等基础组件嵌入式部署、服务器环境、定制化安装如果是刚接触ROS2直接装desktop版就行。它包含的rviz23D可视化工具、gazebo仿真环境、turtlesim小乌龟演示程序都是学习和调试的刚需工具一次性装好省得以后用到哪个再补哪个。执行安装sudo apt install ros-humble-desktop这里有个细节要注意安装过程中如果提示E: Unable to locate package ros-humble-desktop不要急着换包名或者去搜别的教程先回到上一步执行sudo apt update大概率是更新源之后还没刷新软件包列表。4.2 安装过程中的网络与依赖处理ros-humble-desktop的依赖数量相当可观初次安装会拉取几百个软件包总下载体积在1GB以上。如果你使用的是虚拟机且网络一般这个阶段可能耗时很长看起来像是卡住了实际上apt在后台慢慢拉包。两条实用经验不要中断安装。如果中途CtrlC强制终止apt的锁文件会残留下次安装会提示Could not get lock /var/lib/dpkg/lock-frontend还得手动删锁麻烦。安装过程如果报依赖错误大部分是系统自带软件源版本过旧导致的。此时再执行一次sudo apt update sudo apt upgrade -y然后重新安装就能解决。安装完成后可以验证一下核心命令是否可用ls /opt/ros/humble/预期能看到bin、include、lib、share等目录其中bin目录下应该有ros2这个可执行文件。4.3 验证ros2命令是否存在如果你现在直接敲ros2大概率会得到Command ros2 not found。这是正常的因为ROS2的环境变量脚本还没有被加载。确认命令文件存在即可ls /opt/ros/humble/bin/ros2如果这个文件存在说明安装成功只是环境变量没配好——这就是下一节要解决的问题。我在这里额外提一个点如果你装完发现/opt/ros目录不存在说明安装过程中出现了静默失败。重新执行sudo apt install ros-humble-desktop这次留意输出结尾是否有error字样。5. 环境变量配置与colcon工作区搭建装好了不等于能用ROS2的设计逻辑是所有功能包都安装在/opt/ros/humble下但系统不会自动把这些路径加入PATH。你需要手动source环境变量脚本或者在配置文件中持久化设置。5.1 为什么用bash而不直接改bashrc每次打开新终端都要手动执行source /opt/ros/humble/setup.bash显然不现实所以正确做法是写入~/.bashrcecho source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc这里有个因为网络热词也提到的话题——wsl ubuntu写代码最推荐的字体接近macos的体验虽然不是ROS2的核心话题但如果你经常在终端里和ROS2打交道终端字体和配色真的会影响效率和心情。我实测下来在Ubuntu终端里设置JetBrains Mono或者Cascadia Code字体显示中文和日志对齐效果都不错接近macOS的终端体验。具体的字体安装方式在Ubuntu软件中心里搜索安装即可。环境变量配置完成后ros2命令就能直接使用了ros2 --help如果看到命令帮助信息你的核心环境就OK了。但我一般还会顺手验证一下ros2 topic list它能确认通信层正常工作ros2 topic list5.2 创建colcon工作区解决找不到包的根源colcon是ROS2的编译构建工具相当于ROS1时代的catkin用来编译你自己的功能包。很多新手装上ROS2后把功能包放在任意目录下用ros2 run运行结果报Package xxx not found就是因为功能包没有被正确构建和source。创建一个规范的工作区mkdir -p ~/ros2_ws/src cd ~/ros2_ws安装colcon工具sudo apt install python3-colcon-common-extensions现在整个工作区的结构是这样的ros2_ws/ ├── src/ # 存放你自己的功能包源码 ├── build/ # 构建中间文件自动生成 ├── install/ # 安装后的可执行文件和配置自动生成 └── log/ # 编译日志自动生成后续你编写自己的功能包时把源码放在src目录下然后在ros2_ws目录下执行colcon build source install/setup.bash这样才能让ros2 run找到你自己编译的节点。这个工作区推荐也把source ~/ros2_ws/install/setup.bash写入~/.bashrc和系统级的ROS环境变量一起加载避免每次新开终端都要手动sourceecho source ~/ros2_ws/install/setup.bash ~/.bashrc source ~/.bashrc需要特别留意的是install/setup.bash这个文件只有在执行过一次colcon build之后才会生成新创建的工作区第一次执行source会报文件不存在属正常现象先编译一个包或者直接忽略即可。6. 小乌龟与demo验证安装成功与否的判定标准到这里你的ROS2环境已经装完了。但我一直认为判断一个开发环境是否真正可用必须通过一个能实际跑起来的Demo来验证而不是只看ros2 --help能输出帮助信息就算成功。6.1 启动turtlesim的完整流程ROS2自带的turtlesim就是最好的验证工具。执行ros2 run turtlesim turtlesim_node如果一切正常会弹出一个蓝色背景的窗口里面有一只可爱的小乌龟。这个操作看起来简单但实际上验证了以下几个关键链路ros2命令本身可用核心环境配置无误turtlesim功能包能正常找到desktop版的包安装完整GUI显示服务正常X11或者Wayland环境下图形界面能弹出来如果窗口没弹出来大概率是虚拟机里没装图形驱动或者显示配置有问题和ROS2本身关系不大。VMware或VirtualBox用户可以考虑安装open-vm-tools或virtualbox-guest-utils增强工具sudo apt install open-vm-tools-desktop6.2 键盘控制与话题通信的直观理解小乌龟窗口弹出来后新开一个终端执行ros2 run turtlesim turtle_teleop_key然后就可以用键盘的上下左右方向键控制小乌龟移动了。这个演示的核心意义在于它验证了ROS2节点间的通信机制——turtle_teleop_key节点发布键盘按键消息到/turtle1/cmd_vel话题turtlesim_node节点订阅该话题并驱动窗口中的小乌龟移动。用以下命令可以直观看到话题通信的过程ros2 topic list ros2 topic echo /turtle1/cmd_vel后者会实时显示键盘发布的线速度和角速度数据。看到类似输出linear: x: 2.0 y: 0.0 z: 0.0 angular: x: 0.0 y: 0.0 z: 0.0说明通信链路完全正常你的ROS2环境已经可以用于后续的实际开发了。如果你对这个小乌龟还意犹未尽可以尝试让乌龟画个圆之类的ros2 topic pub -r 1 /turtle1/cmd_vel geometry_msgs/msg/Twist {linear: {x: 2.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 1.8}}这会以1Hz的频率向/turtle1/cmd_vel话题发布消息小乌龟会自动绕圈这个操作能更深入理解话题发布机制。7. 我踩过的坑与排查手册按错误现象分条最后这部分是我个人踩坑积累的排查经验全部按错误现象来组织。你如果安装过程中遇到问题直接对照着查就行。7.1E: Unable to locate package ros-humble-desktop这个报错出现的原因就两个字没刷新源。sudo apt update这个命令之后运行一次然后再执行安装。如果apt update能正常跑完但还是找不到包检查一下/etc/apt/sources.list.d/ros2.list里的内容是否正确尤其是jammy拼写和[archamd64 signed-by...]这段有没有写错。我之前见过有人把signed-by写成了sign-by导致apt认为没有签名信息从而跳过了这个源。7.2 密钥失效/签名验证失败报错一般长这样The following signatures couldnt be verified because the public key is not available: NO_PUBKEY 密钥ID我遇到过两次一次是密钥文件下载不完整另一次是系统时间不对导致GPG校验失败。排查思路# 检查系统时间如果时间不对先同步 date sudo apt install ntpdate sudo ntpdate time.windows.com # 重新下载密钥文件 sudo rm /usr/share/keyrings/ros-archive-keyring.gpg sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg然后重新sudo apt update。7.3 安装完成但ros2命令找不到如果/opt/ros/humble/bin/ros2这个文件存在但敲ros2提示找不到命令一定是环境变量没配置好。执行echo source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc还有一种可能你当前用的shell是zsh而不是bash上面写入的是~/.bashrc只在bash生效。如果用的zsh写入~/.zshrc即可。7.4 虚拟机性能相关的卡顿与建议如果你和我一样在虚拟机里跑ROS2rviz2和gazebo这类重型工具可能会卡到怀疑人生。我的建议虚拟机内存至少分配4GB以上8GB最佳处理器核心数至少分配2个以上开启3D加速如果单纯测试通信逻辑不涉及可视化用rviz2的轻量替代方案或者直接在命令行下用ros2 topic echo验证消息收发rviz2启动实在太卡的话还有一个临时方案关闭3D渲染相关插件在启动命令前加LIBGL_ALWAYS_SOFTWARE1强制使用软件渲染LIBGL_ALWAYS_SOFTWARE1 rviz2虽然画面效果一般但能保住不被卡死。另外提醒一句如果你计划在后续项目里用docker microros ros2 humble vscode platformio esp32这套组合给ESP32刷Micro-ROS固件建议直接创建一个已经配置好humble的ubuntu:22.04镜像而不是在Windows上再折腾一套WSL环境。WSL可以跑通常规代码开发但涉及USB设备直通、串口权限这些还是原生Linux或者配置完善的Docker容器更方便。最后补充一个小技巧源里的ROS2包升级是有策略的不要频繁执行apt upgrade升级ROS2相关包。官方在humble的补丁发布节奏上比较保守但偶尔也会有大版本行为变化的补丁混进来。如果你测试好的代码突然行为异常先想想最近是不是升级过ros-humble-*的包必要时用apt-mark hold把某个关键包锁版。我个人的习惯是只更新系统的非ROS软件包ROS2相关的包除非有明确修复了影响我项目的bug否则一律保持原版本不动。