我一直觉得ROS 2 安装这件事本身并不算难真正的痛苦来自“教程太多、版本太乱、旧命令坑人”。尤其是 Ubuntu 22.04 配 ROS 2 Humble网上能找到大量资料但很大一部分还是两三年前写的那时候 apt-key 还能用、环境要求也没今天这么严格直接照抄大概率卡在软件源这一步。这篇文章我打算用一套尽量干净、贴合官方推荐流程的方式从选版本、准备系统、添加软件源、安装主包、初始化环境到跑通 talker/listener 和小乌龟例程再带你把 colcon 工作空间搭起来把整条链路完整走一遍。如果你刚拿到一台 Ubuntu 22.04 的设备或者正在虚拟机和 WSL2 里折腾这篇应该能帮你省下很多不必要的排查时间。1. 安装之前先明确 3 件事1.1 为什么我推荐 Humble而不是 Foxy 或 JazzyROS 2 的版本号和 Ubuntu 发行版有严格的对应关系这一点太容易被忽略了。Humble Hawksbill 对应的正是 Ubuntu 22.04 Jammy Jellyfish两者发布时间基本同步属于官方验证过的 LTS 组合。换句话说你在 22.04 上装 Humble可以直接使用二进制包不需要自己从源码编译整个 ROS 2装完就能跑。如果你目前用的是 Ubuntu 20.04官方对应的是 ROS 2 Foxy如果你用的是 24.04那对应的是 Jazzy。跨版本安装并不是绝对不可能但非常折腾而且很容易出现依赖冲突。很多人问“为什么提示无法定位软件包 ros-humble-desktop”第一个要排查的就是系统版本对不对先执行这句命令cat /etc/os-release把系统版本确认好再继续。我见过不少在 20.04 上去装 humble 包装到一半发现依赖根本对不上最后只能重装系统的情况。1.2 硬件与磁盘规划安装 ROS 2 Humble 桌面完整版安装包加上依赖大概需要 3GB 左右的下载量装完以后占用磁盘空间接近 6GB。如果你还要额外安装 Gazebo、rviz2 插件、各种功能包空间会继续膨胀。所以我建议至少准备 20GB 空闲磁盘空间这个目标不过分。内存方面4GB 是最低要求8GB 用起来会更舒服一些。尤其是后面跑仿真、打开 rviz2再加上 Gazebo 一起运行的时候内存占用增长很快。虚拟机环境里不要给太低的内存别问我是怎么知道的我曾经用 2GB 内存的虚拟机跑 Gazebo 仿真卡得鼠标都挪不动。网络稳定性同样重要。ROS 软件包大多从 packages.ros.org 下载apt 本身支持断点续传但如果你网络经常中断建议多执行几次sudo apt update确认源列表真正刷新成功后再继续。不要嫌这一步啰嗦安装过程里大量时间都是花在网络等待上的。1.3 明确自己的使用场景安装之前你要想清楚到底装桌面版还是基础版。这个选择会影响后续的工具链。如果只是做机器人算法开发、写节点、跑通信基础版或许够用但如果你要学习 ROS 2 的完整体系包括可视化、仿真、TF、SLAM 相关工具桌面版是更合适的选择。我个人的建议是初学者直接装桌面版后面缺什么再用sudo apt install ros-humble-xxx单独补这样既省心又不会漏掉重要组件。2. 全新 Ubuntu 22.04 环境准备2.1 UTF-8 编码为什么要先处理ROS 2 的很多工具和编译脚本依赖 UTF-8 编码官方文档把 locale 配置放在安装步骤之前不是没道理的。很多中文用户在安装系统时选择了中文环境结果locale输出里没有UTF-8后续编译源码时会出现各种奇怪的编码错误。检查一下当前系统的 localelocale如果看到输出中有LANGzh_CN.UTF-8或者LANGen_US.UTF-8说明已经有 UTF-8 环境支持。如果输出比较乱或者不是 UTF-8需要先安装 locales 并重新生成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如果你希望保留中文系统界面也可以把en_US.UTF-8替换成zh_CN.UTF-8作为默认语言。关键是确保最终locale的输出含 UTF-8。改完以后建议重新打开终端或者重新登录用户让新的语言环境变量生效。2.2 安装基础工具接下里安装一些后面一定会用到的工具包括 curl、gnupg2以及用于检测系统版本号的 lsb-releasesudo apt update sudo apt install -y curl gnupg2 lsb-release这里多说一句很多教程写的是lsb_release但实际安装的软件包名是lsb-release。命令里的lsb_release -cs返回的是系统代号Ubuntu 22.04 输出的是jammy后面添加 ROS 软件源时会用到。顺手也建议安装 vim 或者 nano后面修改.bashrc会用到。如果你习惯用 VS Code也可以在系统里装一个编辑文件更方便。这些不是 ROS 2 安装的硬性要求但属于一个不会后悔的前置准备。2.3 不要急着折腾系统软件源网上很多教程上来就教你替换 Ubuntu 软件源这件事我一般劝大家先别做。如果你的网络访问默认源没有问题sudo apt update能顺利完成就完全不需要动系统源。ROS 2 有自己独立的软件源和系统源不是一回事。混着改之后反而容易出现签名错误或依赖关系混乱。如果确实觉得网络太慢也不要在没搞清楚版本代号的情况下随便换源。Ubuntu 22.04 的代号是 jammy任何源的配置都要围绕这个代号来。先执行lsb_release -cs看看系统代号再决定下一步。3. 添加 ROS 2 软件源决定成败的一步3.1 为什么旧教程里的 apt-key 方法已经过时添加软件源这一步是安装过程中翻车率最高的部分没有之一。关键在于密钥管理方式的变化。老教程里常见的做法是curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key | sudo apt-key add -这种把公钥直接丢进系统全局信任列表的做法在 Ubuntu 22.04 里已经不受推荐可能还会导致 apt 给出警告甚至在某些安全配置下直接失效。官方推荐的方案是把 ROS 的公钥单独存成 keyring 文件然后在源配置里通过signed-by指定这个文件。这样做的好处是apt 只会信任你指定的 keyring不会影响到系统全局的密钥池。3.2 官方推荐的添加流程先创建保存密钥的目录sudo install -d -m 0755 /usr/share/keyrings然后下载 ROS 官方的 GPG 公钥并保存到 keyring 文件curl -fsSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg注意ros.key是公开的签名公钥不是敏感内容。下载完成后可以通过ls -l /usr/share/keyrings/ros-archive-keyring.gpg确认文件存在大小通常在几千字节左右。如果文件只有几十字节很可能下载到的是错误页面这时要重新执行一次下载。接着写入软件源列表。执行下面的命令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$(lsb_release -cs)会自动输出系统代号Ubuntu 22.04 就是jammy。这样生成的源配置就是匹配当前系统版本的。3.3 刷新源列表并验证添加完成以后运行sudo apt update正常情况会看到更新列表末尾出现Reading package lists... Done说明源没有问题。如果某个步骤出错这里就会暴露。最常见的错误包括提示ros-archive-keyring.gpg: no public key检查 keyring 文件下载是否完整删除后重新下载。提示The following signatures couldnt be verified because the public key is not available多半是signed-by路径写错了检查/etc/apt/sources.list.d/ros2.list里的路径和实际文件位置是否一致。提示Release file is not valid yet系统时间不对同步一下系统时间再apt update。验证 keyring 是否被正确识别可以执行apt-key list 2/dev/null | grep -A 2 ROS不过这个命令在新版系统中会提示 apt-key 已经废弃不用太在意这只是一种快速查看方式。真正的验证还是看apt update能不能顺利读取 packages.ros.org 的索引。3.4 关于 Docker 场景的补充说明如果你是在 Docker 容器里拉取镜像时遇到unable to find image microros/micro-ros-agent:humble locally这属于另一个层面的问题。这个提示只说明本地不存在该镜像Docker 会尝试从远程仓库拉取拉取失败通常和网络、仓库地址配置、登录状态有关。可以先手动执行docker pull microros/micro-ros-agent:humble看一下具体报错再对症处理。这和我们这里添加 apt 源并没有直接关系但很多人容易把 Docker 的报错和系统安装过程的报错混在一起排查浪费不少时间。4. 安装 ROS 2 Humble 主包4.1 Desktop 完整版和 Base 基础版怎么选ROS 2 Humble 官方提供了两套主要安装目标ros-humble-desktop和ros-humble-ros-base。它们的区别可以简单用下面的表格来表达安装目标包含内容适合场景ros-humble-ros-baseROS 2 核心通信、底层库、基础工具嵌入式、轻量环境、只做通信中间件ros-humble-desktop上述全部 可视化工具、仿真、感知相关包学习、开发、调试、可视化Desktop 完整版包含了 turtlesim、rviz2、demo_nodes、常用感知算法等大量内容。好处是一次装完后续学习时不需要频繁回到安装步骤缺点是下载量大占空间也大。Base 版适合那种磁盘空间紧张或者打算自己从源码编译常用功能包的场景。我的建议很明确如果你是正常学习直接装 Desktop。不要在这个环节过分“省空间”后面缺包时你会不停补装最后装的东西加起来可能比 Desktop 还多。4.2 正式安装命令先刷新软件源sudo apt update然后安装桌面完整版sudo apt install -y ros-humble-desktop这一步会下载大量依赖包耗时十几分钟到半小时不等。看网速。过程里出现红字报错不要慌绝大多数情况是网络抖动导致某个包没有下载完整重新执行一次安装命令apt 会接着下载未完成的部分。如果你选择了基础版此时执行的是sudo apt install -y ros-humble-ros-base其他功能包后续按需安装。例如sudo apt install -y ros-humble-turtlesim sudo apt install -y ros-humble-rviz2安装完成后可以确认一下安装结果ls /opt/ros/humble/正常情况下你会看到bin、include、lib、share、setup.bash等目录和文件。这个/opt/ros/humble/目录就是 ROS 2 的总目录后续所有环境配置都围绕它来。4.3 ros-dev-tools 到底要不要装官方文档里有一个容易被忽略的步骤安装ros-dev-tools。很多人装完ros-humble-desktop后就直接去用colcon build结果提示找不到colcon原因就在这里。执行sudo apt install -y ros-dev-tools这个包会带来一组重要的命令行工具包括colcon、rosdep、catkin相关工具。colcon是现在 ROS 2 推荐的构建工具相当于 ROS 1 时代catkin_make的升级版。没有它你后面很难组织自己写的多个功能包。安装完以后可以用下面的命令验证colcon version-check能正常输出版本信息就说明工具链就绪了。5. 初始化环境与用户配置文件5.1 setup.bash 到底是干什么的/opt/ros/humble/setup.bash是一个环境初始化脚本。它的作用不是简单地设置一个ROS_DISTRO变量而是会修改很多重要的环境变量包括PATH、LD_LIBRARY_PATH、PYTHONPATH、AMENT_PREFIX_PATH等。简单说它告诉系统“ROS 2 的可执行文件在哪儿、库文件在哪儿、Python 模块在哪儿”。如果你不 source 这个文件直接运行ros2命令shell 会告诉你command not found。就算你用绝对路径/opt/ros/humble/bin/ros2把命令跑起来也可能因为找不到库文件而报错。还有一个常见的坑不要试图用.profile来代替.bashrc。.profile只在登录 shell 时读取一次而普通终端窗口打开时读取的是.bashrc。ROS 2 的开发环境需要在每个终端里都生效所以把它写进.bashrc是更合理的做法。5.2 写入 .bashrc 的两种方式最直接的方式是echo source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc这样每次打开新终端环境都会自动加载。如果你想手动管理环境避免每次都自动 source也可以不写入而是每次手动执行source /opt/ros/humble/setup.bash。只是手动操作很容易忘开着开着终端发现ros2命令找不到才想起来没 source。我个人的习惯是自动加载。但要注意一点如果以后你安装了多个 ROS 2 版本比如系统里同时存在 foxy 和 humble不要同时把两个版本的 setup.bash 都写进.bashrc环境变量会被反复覆盖后加载的版本会顶掉前面的很容易引发混乱。5.3 环境变量检查方法配置完成后验证一下当前环境是否正常。常用的几个命令echo $ROS_DISTRO如果输出humble说明版本变量正确。再执行printenv | grep -E ROS|AMENT你会看到ROS_DISTRO、AMENT_PREFIX_PATH、ROS_VERSION等一堆变量。其中ROS_VERSION应该是2ROS_PYTHON_VERSION是3。到这里ROS 2 主环境就已经配置好了。很多人认为安装过程到此结束其实这只是开始真正的验证要看能不能跑起来一个完整的通信例程。6. 第一个 ROS 2 程序6.1 用 talker/listener 验证通信链路安装成功最经典的验证方式就是运行官方自带的 C 和 Python 节点让它们互相通信。先打开第一个终端启动一个发布者节点ros2 run demo_nodes_cpp talker如果一切正常你会看到类似下面的输出[INFO] [1710000000.123456789] [talker]: Publishing: Hello World: 1 [INFO] [1710000000.623456789] [talker]: Publishing: Hello World: 2在这个终端保持运行的同时打开第二个终端启动一个订阅者节点ros2 run demo_nodes_py listener正常情况下第二个终端会打印[INFO] [1710000000.223456789] [listener]: I heard: [Hello World: 1]这说明发布者和订阅者已经通过某个话题完成了消息传递。这个过程背后涉及 DDS 的节点发现机制第一次运行时可能会有一两秒的等待这属于正常的 discovery 过程。如果 listener 一直收不到数据只有 talker 在那里打印先不要怀疑 ROS 2 没装好重点检查两个终端的环境是否都正确 source 了网络是否存在问题以及防火墙是否拦截了 DDS 使用的 UDP 端口。6.2 初识小乌龟 turtlesimtalker/listener 还不够直观turtlesim 才是最适合新手的第一个图形化例程。turtlesim 已经包含在 desktop 完整版里不需要额外安装。如果想确认一下可以执行ros2 pkg list | grep turtlesim有输出就说明包在。接下来启动小乌龟窗口ros2 run turtlesim turtlesim_node你会在屏幕上看到一个蓝色背景的窗口中央有一只小乌龟。这个节点会一直运行监听速度指令话题。再开一个终端启动键盘控制节点ros2 run turtlesim turtle_teleop_key然后在键盘上按方向键小乌龟就会在窗口里移动并画出线条。这个看起来简单的小实验背后是两个节点通过cmd_vel话题进行通信的过程。一个节点发布速度消息另一个节点订阅并控制乌龟的运动。你可以用下面命令看看正在运行的话题ros2 topic list ros2 topic echo /turtle1/cmd_vel后一条命令会实时显示乌龟收到的速度指令。这是理解 ROS 2 话题通信机制非常好的窗口。6.3 rviz2 可视化上手rviz2 是 ROS 2 里最常用的可视化工具也在 desktop 版中自带。直接运行rviz2如果使用命令行完整写法也可以这样ros2 run rviz2 rviz2打开以后你会发现整个界面是空的这是正常现象。在左侧面板的Displays区域点击Add可以添加多种显示组件比如RobotModel、Grid、TF等。首次使用时记得在Global Options里把Fixed Frame设置成实际存在的坐标系否则很多显示会出现 warning。rviz2 本身不产生数据它更像一个“可视化前端”用来订阅并展示其他节点发布的 TF、PointCloud2、LaserScan 等消息。以后你做地图构建、导航避障基本都是靠它来看效果。7. 使用 colcon 管理自己的项目7.1 工作空间目录结构安装完 ROS 2理解如何组织自己的项目代码是进入应用阶段的关键。ROS 2 默认推荐使用 colcon 构建工具工作空间通常包含src、build、install、log四个目录。src存放功能包源码build构建过程中生成的中间文件install构建完成后的可执行文件和环境脚本log编译日志要新建一个工作空间执行mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src这个ros2_ws就是你的主工作空间名字可以随意取但建议统一用字母和下划线不要用中文或空格。7.2 创建第一个功能包在src目录下创建一个新包ros2 pkg create --build-type ament_cmake my_package其中--build-type ament_cmake指定这个包用 C 的 CMake 构建体系。如果你想创建 Python 的包则使用ament_python。创建完成后进入顶层工作空间目录进行构建cd ~/ros2_ws colcon build --symlink-install--symlink-install是我个人强烈建议加的参数。它的作用是让install目录里的文件以软链接方式指向src目录里的源码。这样你修改 Python 脚本后不用重新构建就能直接生效开发体验好很多。如果用 C修改后还是要重新 build但 Python 逻辑改动确实能省掉重复构建的时间。构建结束后加载自己工作空间的环境source install/setup.bash然后试着运行一下包里自带的节点模板ros2 run my_package my_package_node如果是完整版的默认模板你应该会看到一个简单的日志输出。7.3 让工作空间自动加载每次打开新终端都要手动source install/setup.bash很麻烦所以我建议把它加进.bashrc。但注意顺序echo source /opt/ros/humble/setup.bash ~/.bashrc echo source ~/ros2_ws/install/setup.bash ~/.bashrc顺序很重要先加载 ROS 2 全局环境再加载自己的工作空间环境。这样你自己包的路径会排在 ROS 2 全局路径前面如果发生同名包系统会优先加载你的工作空间版本。如果顺序反了你写的包可能会被全局包遮蔽运行的时候还是会走旧版本。还有一点要特别注意工作空间里有install目录的前提是已经执行过至少一次colcon build。如果你新克隆了一个仓库到src但还没 build就直接打开新终端 source install/setup.bash系统会提示路径不存在这时需要先回到工作空间执行构建命令。8. 常见问题与排查技巧实录8.1 找不到命令、无法定位软件包这类问题是最常见的。我整理了一个快速排查表格现象大概率原因处理方式ros2: command not found环境未 source执行source /opt/ros/humble/setup.bashUnable to locate package ros-humble-desktopROS 软件源没添加或没刷新检查/etc/apt/sources.list.d/ros2.list重新sudo apt updatePackage ros-humble-desktop is not availableUbuntu 版本与 Humble 不对应执行cat /etc/os-release确认系统版本E: Unmet dependencies网络或系统源问题先sudo apt --fix-broken install再重试如果遇到ros2: command not found先检查.bashrc末尾有没有 source 那行。很多人改完.bashrc后没有开新终端就直接敲命令这也会报错。可以直接在同一个终端执行source ~/.bashrc让它生效。8.2 节点发现不了通信失败如果你已经启动了 talker 和 listener但两边就是“各说各的”大概率卡在 DDS 网络通信上。ROS 2 底层用的是 DDS多台机器之间通过 UDP 多播进行节点发现。下面几种情况最容易出问题两台机器不在同一个局域网网段发现消息无法广播。防火墙拦截了 UDP 端口。DDS 默认会使用一些动态端口如果开了防火墙需要放行相关端口的 UDP 流量。ROS_DOMAIN_ID不一致。如果多个终端或不同机器设置了不同的 domain ID节点之间互相看不见就像用了不同的“聊天频道”。单机环境下出现问题先确认环境变量没有设置奇怪的 domainecho $ROS_DOMAIN_ID如果输出为空默认就是 0。如果你之前研究过别的项目把ROS_DOMAIN_ID设成了自定义值而新终端没有同步设置就会出现“我明明启动了节点但就是发现不了”的诡异情况。8.3 WSL2 和虚拟机环境专项Windows 上使用 WSL2 安装 Ubuntu 22.04 再装 ROS 2 是可行的而且使用体验越来越接近原生 Linux。不过有两点要特别注意。第一确认你的 WSL 版本足够新并且已经启用 WSLg。WSLg 允许 WSL2 里的图形应用直接显示到 Windows 桌面否则你启动 rviz2 时会出现无法连接显示服务器的错误。执行wsl --update可以确保 WSL 相关组件是最新版。第二在 WSL2 里测试 turtle 窗口和 rviz2 时不建议再去手动配置 X11 转发那套东西。WSLg 正常的情况下直接运行rviz2就会弹窗。如果不弹窗先看有没有输出关于DISPLAY的错误再确认 Windows 侧的 WSLg 是不是被禁用了。虚拟机环境比如 VMware 或 VirtualBox装 Ubuntu 22.04 时网络模式建议使用桥接不要用 NAT。NAT 模式下虚拟机和外部的 ROS 2 设备通信会非常困难。图形性能上如果只是跑 rviz2默认设置就够用如果要跑 Gazebo 重仿真内存和 CPU 核心数尽量多给一些。8.4 构建依赖错误colcon 构建时最常见的问题是Package xxx not found或者Could not find a package configuration file provided by xxx这种情况一般是当前环境里没有加载对应功能包。如果你已经安装了某个 ROS 功能包但 colcon 找不到它可以先确认全局环境是否 sourcesource /opt/ros/humble/setup.bash然后重新构建。如果是自己写的包之间互相依赖先确认被依赖的包在install目录里已经生成并且你已经执行过source install/setup.bash。还有一种情况是 Python 依赖缺失比如ModuleNotFoundError: No module named catkin_pkg。不要一上来就pip3 install catkin_pkg覆盖系统 Python 环境这很容易和系统的包管理冲突。建议优先用 apt 安装 ROS 官方打包好的版本或者用虚拟环境隔离。8.5 后续扩展Docker 与 micro-ROSROS 2 安装好以后你会慢慢接触一个越来越热门的领域嵌入式 ROS 2也就是 micro-ROS。简单说micro-ROS 能让 ESP32、STM32 这类资源受限的微控制器和 ROS 2 系统通信。这里经常会用到 Docker 来运行 micro-ROS Agent。如果你的环境下执行docker run --rm -it --nethost microros/micro-ros-agent:humble提示unable to find image microros/micro-ros-agent:humble locally说明本地没有这个镜像标签Docker 会尝试从远程拉取。手动先拉取一次docker pull microros/micro-ros-agent:humble再看看具体报错是网络原因、仓库地址原因还是 Docker daemon 没有正常运行。这种问题通常和 ROS 2 安装无关把它和系统安装阶段的错误混在一起排查只会越查越乱。装完 ROS 2 Humble 之后我自己习惯先跑一轮 talker/listener 再继续装其他功能包。这样做最大的好处是把环境配置和后续问题隔离开来后面如果出现奇怪的现象至少能确定 ROS 2 底层通信是健康的。再往后你完全可以按照自己的项目需求慢慢安装导航、建图、机械臂、视觉相关功能包。ROS 2 的生态很大安装只是第一步真正有价值的是理解节点如何协作、消息如何流动以及如何把这些机制应用到你的真实机器人系统中。