Ubuntu 22.04安装ROS2 Humble完整指南与colcon工作空间搭建

很多人第一次接触ROS2，都会被安装这一步劝退。不是因为没有教程，而是因为教程版本太多太乱，有的讲20.04，有的讲WSL2，有的直接甩给你一串命令装完就闪人，结果你照着一顿操作下来，ros2命令打不出来，小乌龟起不来，中文乱码，源冲突，一天就这么没了。

这篇文章我只讲一件事：在全新的Ubuntu 22.04上，把ROS2 humble完整装好，跑通示例，再顺手搭好一个能长期开发用的工作空间。

我写的是完整可复现的流程，每一步都会解释为什么要这样做，以及遇到什么现象说明你走对了。里面大部分坑都是我实际踩过的，不是网上那种复制粘贴的说明书。适合第一次装ROS2的小白，也适合以前装过ROS1但现在要切到ROS2的开发者参考。

1. 安装前的思路：版本选择和方案权衡

1.1 为什么是Ubuntu 22.04 + ROS2 humble

ROS2每个版本都有一个对应的Ubuntu LTS版本，这不是随便配的，而是官方做了完整测试和支持的组合。目前长期支持版本里最稳的一对，就是Ubuntu 22.04（代号jammy）配合ROS2 humble（全称Humble Hawksbill）。

之前很多人还在用ROS2 foxy配Ubuntu 20.04，但foxy在2023年5月已经停止维护了，这意味着之后官方不再发布针对foxy的安全补丁和bug修复。而humble的维护周期到2027年，对学习、科研、产品原型开发都足够用。

另外Jazzy对应的是Ubuntu 24.04，虽然更新，但很多第三方设备驱动、SDK、教学资料还停留在humble时代。如果你是跟着课程或开源项目学习，大概率能找到的参考资料都是基于humble的。所以我的建议很直接：2025年这个时间点，学习或者做项目，Ubuntu 22.04 + ROS2 humble就是最优解。

1.2 ROS2和ROS1的区别先说清楚

如果你之前接触过ROS1，这里必须先转变一个观念：ROS2没有roscore，也不存在master节点。ROS2的节点之间通过DDS协议自动发现、直接通信，节点A和节点B只要在同一个网络域（默认domain ID为0）里，就能自动找到对方。

这个变化带来的直接体验就是：以前启动ROS1之前必须先启动roscore，ROS2完全不需要。我见过太多从ROS1转过来的同学，装完ROS2之后第一反应是“roscore呢”，然后到处找命令——根本不存在的。你直接ros2 run启动节点，它自己就能工作。

还有一点要注意，ROS2的启动方式也变了：rosrun变成了ros2 run，话题列表变成ros2 topic list，节点列表是ros2 node list。命令体系完全重写了一遍，后面的验证部分我会一步步展示。

1.3 环境方案：物理机、虚拟机、WSL2还是Docker

在开始动手之前，先想清楚你打算把ROS2装在哪里。

如果你是第一次装，我建议直接用物理机双系统。因为后面你可能要接真实硬件，比如STM32、ESP32、激光雷达，这些在虚拟机里的USB透传虽然能做，但经常出现延迟和设备识别失败的问题，非常搞心态。

如果你实在不想重装系统，虚拟机里用Ubuntu 22.04 Server版再加桌面环境也可以，但记得给虚拟机分配至少4GB内存、双核CPU以上，否则编译和启动RViz2会卡到怀疑人生。WSL2的话我也试过，跑纯命令行程序没问题，但打开RViz2这种图形工具需要额外配置WSLg，有些机器上会很玄学。

2. 换源与系统基础配置：这一步决定后面是否顺利

2.1 换国内apt源，别在这一步偷懒

如果你在国内，安装软件源这一步不能跳过。Ubuntu默认的源服务器在国外，直接sudo apt update你可能会等到崩溃，或者是装了十分钟卡在某个包上下载失败。

先把软件源换成国内镜像，这里以清华源为例。Ubuntu 22.04的源配置在/etc/apt/sources.list，操作前先备份：

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

然后编辑文件，把里面的archive.ubuntu.com和security.ubuntu.com全部替换为mirrors.tuna.tsinghua.edu.cn。如果你不想手动改，可以直接用sed：

sudo sed -i 's@//.*archive.ubuntu.com@//mirrors.tuna.tsinghua.edu.cn@g' /etc/apt/sources.list sudo sed -i 's@//security.ubuntu.com@//mirrors.tuna.tsinghua.edu.cn@g' /etc/apt/sources.list

改完之后更新一下：

sudo apt update

看到下载速度上来，说明源生效了。这里顺便提一句：ROS2本身的二进制包存储在packages.ros.org，这个地址国内访问有时候快有时候慢，如果后面在安装ros-humble-desktop时下载很慢，可以把ROS源也换成国内镜像，常见的阿里、中科大都有ROS源镜像。不过先别急着全换，系统源换好后，试试看后面安装ROS2时速度如何，能用就用，别过度配置。

2.2 设置UTF-8语言环境

这一步在官方文档里都有，但是中文教程里很多人会忽略。ROS2在运行过程中会用到一些对locale敏感的脚本，如果系统locale不是UTF-8，后续可能会在构建工作空间或者运行rosdep时出现奇奇怪怪的报错，比如：

Locale not supported by C library.

为了避免这个问题，我们预先设置好语言环境：

sudo apt update && sudo apt install locales -y sudo locale-gen en_US en_US.UTF-8 sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8 export LC_ALL=en_US.UTF-8 source /etc/profile

这里有个细节：update-locale写的是/etc/default/locale，这个文件在系统启动时被读取。你执行完source /etc/profile后当前终端生效了，但新开的终端可能还是读取旧的locale。所以最稳妥的做法是执行完上面命令后，reboot重启一次系统，再继续后面的操作。

2.3 安装基础工具

装ROS2之前，先把系统里最基础的工具装齐。这些不是ROS2的依赖，而是我们日常开发要用的东西：

sudo apt update sudo apt install -y curl wget git vim net-tools python3-pip

其中curl很关键，后面添加ROS2 GPG密钥的时候要用，python3-pip用于安装Python包，git用于拉取代码。都是基础中的基础，顺手装一下不亏。

3. 正式安装ROS2 Humble

3.1 添加ROS2软件源和GPG密钥

Ubuntu本身不包含ROS2的软件包，所以我们要手动把ROS2的软件源添加到系统里。这一步包含两层操作：下载GPG密钥，然后写入源列表。

先安装curl确保可用（刚装完应该已经有了），然后下载密钥：

sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

这里解释一下为什么要放到/usr/share/keyrings/目录下：Ubuntu 22.04时代，apt要求第三方源的GPG密钥必须放在keyrings目录里，并且源配置里用signed-by=参数指定，这样apt在验证包的时候就知道用哪个密钥，不会污染整个系统的信任链。老教程里那种直接丢到/etc/apt/trusted.gpg.d/的做法现在已经不推荐了，如果混用容易出警告甚至报错。

然后添加ROS2源列表：

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(source /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

这条命令里有两个值得注意的地方：$(dpkg --print-architecture)会自动获取当前系统架构，大部分人是amd64，不用手动写死；$(source /etc/os-release && echo $UBUNTU_CODENAME)会读出系统代号，Ubuntu 22.04识别出来的就是jammy，这样源地址就变成了http://packages.ros.org/ros2/ubuntu jammy main。版本维护起来很方便，以后升级系统版本后这个地址也能跟着变。

添加完成后更新一下软件包列表：

sudo apt update

如果这里没有报错，说明ROS2源已经成功接入。你可以用apt-cache search ros-humble | head看一眼，应该能列出大量ros-humble-*开头的软件包。

3.2 升级系统并安装ROS2桌面版

接下来更新系统包库信息，顺手升级一下系统中已有的软件包：

sudo apt update sudo apt upgrade -y

注意，upgrade这一步时间取决于你的网络和机器状况，如果内核或者其他大件有更新，可能会比较久。但别省这一步，有时候ROS2的依赖包版本和系统仓库里的不一致，提前升级一次能避免后面很多依赖冲突。

然后选择要安装的ROS2版本。ROS2有两种常用安装级别：

• ros-humble-desktop：包含RViz2、Gazebo、demo节点、各种可视化工具，功能最全
• ros-humble-ros-base：只有基础的通信库和命令行工具，没有图形界面

第一次装，直接装desktop版，一步到位：

sudo apt install ros-humble-desktop -y

这个包体积很大，包含数百个依赖，下载时间取决于网络。装的时候别闲着，可以看看输出，了解都装了哪些东西，对后续理解ROS2模块构成很有帮助。

如果你以后要做机器人导航、SLAM、MoveIt等，后面按需apt install ros-humble-<功能包名>即可，不用现在一股脑全装。

3.3 配置环境变量

安装完成后，ROS2的可执行文件在/opt/ros/humble/目录下。如果你此刻直接打开一个终端输入ros2，大概率会提示找不到命令，因为系统还没告诉你这个工具在哪里。

我们把这个路径配置到shell的启动文件里，这样每次打开终端就能自动加载ROS2环境：

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc source ~/.bashrc

这里解释一下setup.bash的作用：ROS2的环境变量、可执行文件路径、库搜索路径都是靠这个脚本配置的。你以后创建自己的工作空间，也会生成一个install/setup.bash，原理完全一样。可以理解为：运行环境变量集中在一处，source一下就全部生效。

验证一下是否配置成功：

echo $ROS_DISTRO

如果输出humble，说明环境变量已经生效。再输入：

ros2 --help

能看到命令帮助列表，说明ROS2命令已经可用。

这个步骤我见过太多人栽跟头：命令明明执行了，但是新开的终端还是找不到ros2，原因就是你只在当前终端source了，没写进.bashrc。记住，是echo ... >> ~/.bashrc写入，不是用完就忘。另外，如果你用zsh，那么文件应该是.zshrc，命令里的bash也要改成zsh。

3.4 安装常用的开发工具链

刚才装的ros-humble-desktop已经包含ROS2本身的功能，但实际开发还需要几个配套工具：

sudo apt install -y python3-colcon-common-extensions python3-rosdep python3-rosinstall-generator python3-vcstool

这里逐个说下用途：

• colcon：ROS2的编译工具，替代ROS1里的catkin_make。以后你编写自己的功能包，就是在工作空间里运行colcon build来编译
• rosdep：自动安装功能包依赖的系统库。你从网上clone一个项目下来，项目里的package.xml会声明它依赖哪些库，rosdep能自动帮你查缺补漏
• vcstool和rosinstall-generator：批量管理多个源码仓库的工具，做多包项目时会用到

装完后建议顺手初始化rosdep：

sudo rosdep init rosdep update

rosdep init如果提示已经初始化过，说明你之前装过ROS1相关的环境，不用管，直接执行rosdep update即可。这个步骤偶尔会因为网络问题失败，多试几次就好，不影响ROS2本身使用。

如果你确定以后要做Gazebo仿真，还可以安装Gazebo的ROS2接口包：

sudo apt install -y ros-humble-gazebo-ros-pkgs

这个包让Gazebo能跟ROS2节点通信，比如从话题里读取速度指令，或者发布传感器数据。不做仿真可以跳过，后面想装再装也行。

4. 验证安装：用小乌龟把系统跑起来

4.1 启动小乌龟节点

装完之后最直观的验证方式就是跑官方的小乌龟示例。这个例子几乎所有ROS2教程里都会用到，因为它是图形化、交互式、能直观看到节点通信过程的最简单演示。

打开一个终端，启动小乌龟仿真器：

ros2 run turtlesim turtlesim_node

一个蓝色背景的小窗口会弹出来，窗口中央有一只小乌龟，如果一切正常说明ROS2基础环境没问题。

接着再开一个新终端，运行键盘控制节点：

ros2 run turtlesim turtle_teleop_key

然后回到这个终端，按键盘方向键，小乌龟就会跟着移动。它走过的路径会留下一条彩色的轨迹。

说明一下这里的ros2 run用法：ros2 run <包名> <可执行文件名>，第一个参数是功能包名，第二个参数是包里的可执行程序。ROS2的官方示例包叫turtlesim，里面有两个可执行程序，一个负责图形显示，一个负责读取键盘输入。这两个程序各自是一个独立的节点，它们之间通过话题/turtle1/cmd_vel通信，这就是分布式通信的最直观体现。

4.2 用命令行工具查看节点和话题

小乌龟跑起来之后，打开第三个终端，可以用ROS2自带的命令行工具查看系统里正在运行什么：

ros2 node list

你应该能看到两个节点：

/teleop_turtle /turtlesim

再看一下话题列表：

ros2 topic list

你会看到/turtle1/cmd_vel、/turtle1/pose、/turtle1/color_sensor等话题。其中/turtle1/cmd_vel就是键盘节点发布速度指令、乌龟仿真器订阅速度指令的那条通信管道。

进一步，你可以实时监听这条话题里传输的数据：

ros2 topic echo /turtle1/cmd_vel

然后回到键盘控制终端按一下方向键，你会发现echo终端里立刻显示了一组Twist类型的数据，包含线速度和角速度。这说明两个节点之间的通信是实时、双向的。

还可以直接通过命令行给话题发指令，不用键盘也能控制乌龟：

ros2 topic pub --once /turtle1/cmd_vel geometry_msgs/msg/Twist "{linear: {x: 2.0}, angular: {z: 1.8}}"

这条命令发布一次速度指令，乌龟会以一个弧线运动一下。--once表示只发一次，不加的话会持续发送。

4.3 测试RViz2

小乌龟验证的是基础的节点通信，接下来验证图形可视化工具RViz2是否正常：

ros2 run rviz2 rviz2

RViz2的主界面会弹出。第一次打开可能是纯黑色背景，这正常，因为你还没有加载任何话题数据。你可以在左侧Display面板里点击Add，选择By topic，然后添加/turtle1/pose等话题，这样窗口里就能看到乌龟位姿的可视化效果。如果RViz2能正常打开且界面不卡死，说明你的ROS2图形环境已经完整配置好了。

5. 创建第一个ROS2工作空间：colcon环境布置

5.1 理解colcon的overlay机制

环境跑通之后，接下来要做的是搭建你自己的开发环境。ROS2的编译系统和ROS1的catkin不太一样，它用的是colcon。colcon构建的结果放在工作空间下的install/目录里，你写好的源码放在src/目录下。

这里有个重要的概念叫overlay：系统安装的ROS2环境是底层（underlay），你自己工作空间编译出来的包是上层（overlay）。当你source了工作空间的install/setup.bash之后，你新建的包会“覆盖”在系统ROS2环境之上，不会污染系统目录。这也就是为什么ROS2多项目切换比ROS1干净很多。

5.2 动手创建并构建工作空间

在终端里执行：

mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src

现在这个src目录还是空的，但我们可以先跑一次空构建，把整个工作空间的骨架搭出来：

cd ~/ros2_ws colcon build

此时你会在~/ros2_ws下看到三个新的目录：build、install、log。build是编译中间文件目录，install是编译产物目录，log是日志目录。这三个目录默认都要写入.gitignore，不用提交到版本控制里。

接着让终端识别这个工作空间的环境：

source install/setup.bash

由于这是第一次构建、还没有任何功能包，source之后不会增加新的命令，但这个source操作验证了环境是通的。

以后你在src里放了自己的功能包（比如复制一份turtlesim改改），就是重复这个流程：

cd ~/ros2_ws colcon build source install/setup.bash

这三个命令以后会成为你的日常。有一点值得注意：如果你改动了环境变量或者新增了功能包，必须重新构建并source，新功能才能在当前终端里被识别。如果嫌每次忘source，可以像前面把setup.bash写进.bashrc一样，把source ~/ros2_ws/install/setup.bash也追加进去，但我觉得开发阶段还是手动source比较好，避免不同工作空间交叉覆盖。

6. 常见问题与排查技巧实录

6.1 找不到ros2命令

bash: ros2: command not found

出现这个基本是环境变量没配置好。先确认一下你source的是哪个文件：source /opt/ros/humble/setup.bash。然后确认这个命令有没有写进.bashrc。如果你用zsh，要写.zshrc。还有一种情况是你之前装过别的ROS版本，两个版本的setup.bash互相覆盖了，检查一下/opt/ros/下面有哪些目录，只保留当前要用的那一个source行。

我之前帮人排查过的最诡异案例，是.bashrc里source了某虚拟环境路径，导致每次开终端就停在某个特定环境下，ROS2的环境变量被挤掉了。遇到这种情况，把.bashrc里多余的source行注释掉，重新开终端再试。

6.2 安装时下载速度慢或超时

如果apt install ros-humble-desktop时下载特别慢，优先考虑换源和重试。ROS2的默认软件源在packages.ros.org，国内访问速度不稳定。可以临时把/etc/apt/sources.list.d/ros2.list里的地址替换为镜像地址，比如中科大或阿里的ROS源。替换后记得sudo apt update。

还有一个比较隐蔽的问题：如果你开了系统代理或者某些网络加速工具，apt的下载可能走代理反而更慢。临时关闭代理再试一次，经常有奇效。

6.3 GPG key相关报错

The following signatures couldn't be verified because the public key is not available

说明GPG密钥下载失败或者不完整。重跑一次下载命令，确认密钥文件存在且非空：

sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg ls -l /usr/share/keyrings/ros-archive-keyring.gpg

密钥文件大小一般在几千字节，如果只有几百字节，大概率是下载到了错误页面，需要重新下载。另外检查ros2.list里的signed-by路径是否和密钥文件实际位置一致。

6.4 其他可选的安装方式说明

现在网络上有些教程会推荐用snap安装ROS2，命令是sudo snap install ros2-humble之类的。我只能说，这个方式我自己试过一次就放弃了：snap版本的ROS2和常规apt方式安装的附加包混用非常麻烦，很多ros-humble-*功能包不能直接往snap环境里装，而且社区的支持资料基本都是基于apt安装方式的。初学者老老实实用官方apt方式，少给自己添堵。

另外如果你是做嵌入式方向，之后可能要碰micro-ROS和ESP32，那又是另一套工具链了。micro-ROS主要是把ROS2通信能力跑到MCU上，跟本文讲述的Ubuntu环境安装是两件事。先把桌面端的ROS2学好，硬件那块后面接触时会轻松很多。

6.5 小乌龟窗口乱码或字体异常

小乌龟窗口里的文字显示成方块或者乱码，一般是系统缺少中文字符集或者字体渲染问题。在Ubuntu 22.04桌面版上，可以安装```

sudo apt install fonts-noto-cjk -y

来解决中文字体显示问题。如果是在虚拟机里，也可能是显卡驱动性能不足，导致渲染异常。这个不影响ROS2本身功能，但看着确实难受，装个字体大多数情况能改善。 ### 6.6 RViz2启动闪退或白屏 RViz2启动后立刻崩溃，常见原因有两个：一是机器显卡驱动太老，OpenGL版本不够；二是虚拟机环境里3D加速没开启。先试试在启动RViz2前加上软件渲染： ```bash export LIBGL_ALWAYS_SOFTWARE=1 ros2 run rviz2 rviz2

如果软件渲染下能正常打开，说明是OpenGL硬件加速问题，去把显卡驱动更新一下（比如NVIDIA装官方驱动），或者在虚拟机设置里开启3D加速。

以上问题排查完，你的Ubuntu 22.04 + ROS2 humble环境应该就稳了。我个人在实际操作中的体会是：ROS2安装本身不难，难的是环境叠加太久之后的各种冲突。所以从一开始就养成好习惯——新开一个项目就建独立工作空间，环境变量只保留需要的source，别把一堆东西全堆在.bashrc里。按照这套流程搭好底子，后面写节点、做仿真、接硬件，你会比那些环境乱糟糟的人舒服得多。