在 Ubuntu 22.04 上从零安装配置 ROS2 Humble

最近开始折腾小机器人，用一台 x86 小主机做主控，装 ROS2 来控制。这篇记录一下在 **Ubuntu 22.04** 上安装 **ROS2 Humble** 的完整流程，重点把国内网络环境下踩到的两个坑写清楚——这俩坑让我多花了不少时间，希望能帮到同样在国内装 ROS2 的朋友。

为什么是 Ubuntu 22.04 + ROS2 Humble

ROS 的版本和 Ubuntu 版本是强绑定的，装错组合会非常痛苦。对应关系：

| Ubuntu 版本 | 推荐 ROS2 版本 | 支持周期 |
|---|---|---|
| 22.04 (Jammy) | Humble (LTS) | 到 2027 年 |
| 24.04 (Noble) | Jazzy (LTS) | 到 2029 年 |
| 20.04 (Focal) | Foxy / ROS1 Noetic | 已 EOL |

ROS1 已经在 2025 年彻底停止维护，新项目不用再考虑。如果你的系统是 22.04，那 Humble 是目前最成熟稳妥的选择，本文以此为例。

> 确认你的系统版本：lsb_release -a

第 0 步：确认 locale

ROS2 要求 UTF-8 编码的 locale。先检查：

locale   # 看是否有 UTF-8

如果没有，设置一下：

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

第 1 步：配置软件源

启用 universe 仓库，添加 ROS2 的 GPG key 和 apt 源：

# 1. 基础工具 + universe 仓库
sudo apt update
sudo apt install -y software-properties-common curl gnupg lsb-release
sudo add-apt-repository -y universe

# 2. 添加 ROS2 GPG key
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key 
  -o /usr/share/keyrings/ros-archive-keyring.gpg

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

sudo apt update

⚠️ 国内避坑（重点）

直接 apt install ros-humble-desktop 时，我连续两次失败，报错分别是：

**坑一：IPv6 不通，apt 一直在死磕 IPv6**

E: Failed to fetch http://packages.ros.org/... 
   Cannot initiate the connection to packages.ros.org:80 (2600:3402:...). 
   - connect (101: Network is unreachable)

很多机器/网络没有可用的 IPv6，但 apt 默认会优先尝试 IPv6 地址，结果一直 Network is unreachable。**解决办法：强制 apt 走 IPv4**，在所有 apt 命令加 -o Acquire::ForceIPv4=true：

sudo apt-get -o Acquire::ForceIPv4=true install -y ros-humble-desktop

想永久生效，可以写进配置：

echo 'Acquire::ForceIPv4 "true";' | sudo tee /etc/apt/apt.conf.d/99force-ipv4

**坑二：默认 Ubuntu 镜像不稳定，个别包反复下载失败**

强制 IPv4 后，ROS 的包能下了，但 Ubuntu 自带源（cn.archive.ubuntu.com）里有几个包（视频驱动类，如 i965-va-driver、va-driver-all、proj-bin 等）反复 Unable to connect，最后 apt 报 held broken packages 直接中止整个安装。

**解决办法：把 Ubuntu 源换成稳定的国内镜像**（清华或阿里都行）。先备份再替换：

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

# 换成清华源
sudo sed -i -E 
  's|https?://(cn.archive|security).ubuntu.com/ubuntu/?|https://mirrors.tuna.tsinghua.edu.cn/ubuntu/|g' 
  /etc/apt/sources.list

sudo apt-get -o Acquire::ForceIPv4=true update

> 小技巧：换源前先用 curl -4 -o /dev/null -w "%{http_code} %{time_connect}sn" https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ 测一下哪个镜像快又通，再决定换哪个。

第 2 步：安装 ROS2

避坑配置就位后，安装就顺了。desktop 版本包含 RViz、demo、turtlesim 等可视化和示例工具，适合学习：

sudo apt-get -o Acquire::ForceIPv4=true install -y 
  ros-humble-desktop 
  ros-dev-tools 
  python3-rosdep 
  python3-colcon-common-extensions

- ros-humble-desktop：核心 + RViz + demo（约 2GB+）
- ros-dev-tools：开发工具集
- python3-rosdep：依赖管理
- python3-colcon-common-extensions：构建工具

> 下载量大，建议放后台跑，或用 tmux/nohup 防止 SSH 断连中断。下载完成后会进入解包/配置阶段，此时没有网络流量是正常的，别误以为卡住了。

第 3 步：配置环境变量

让每次开终端自动加载 ROS 环境：

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
echo "export ROS_DOMAIN_ID=0" >> ~/.bashrc
source ~/.bashrc

ROS_DOMAIN_ID 用于隔离同一局域网内不同的 ROS2 系统，默认 0 即可，多人/多机环境再按需区分。

第 4 步：初始化 rosdep

rosdep 用于自动安装功能包的系统依赖，后续编译别人的包时几乎必用：

sudo rosdep init
rosdep update

> rosdep update 会从 GitHub 拉取索引，国内偶尔会超时。多试几次，或配置 GitHub 镜像/代理。

第 5 步：验证安装（talker / listener）

ROS2 的"Hello World"——一个节点发消息，另一个收消息。开两个终端：

# 终端 1
ros2 run demo_nodes_cpp talker

# 终端 2
ros2 run demo_nodes_py listener

如果 listener 持续打印 I heard: [Hello World: N]，且编号和 talker 发布的对得上，说明 ROS2 的节点发现和 DDS 通信完全正常。✅

再试试经典的小乌龟：

ros2 run turtlesim turtlesim_node

第 6 步：建一个工作区

后续自己写包都放工作区里。建好并用 colcon 验证一下工具链：

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws
colcon build          # 空工作区也能跑通，验证 colcon 正常
echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc

构建后会生成 build/、install/、log/ 三个目录。注意 .bashrc 里 **先 source 系统的 /opt/ros/humble，再 source 工作区的 overlay**，顺序不能反。

小结

国内装 ROS2，90% 的坑都在网络上。记住两条：

1. 强制 IPv4：-o Acquire::ForceIPv4=true
2. 换国内镜像：清华 / 阿里

剩下的就是按官方流程一步步来。装完跑通 talker/listener，就可以开始你的机器人开发之旅了。

---

*环境：Ubuntu 22.04.5 LTS / x86_64 / ROS2 Humble*