ROS2 安装完全指南（Ubuntu 版）：从零开始到跑通第一个节点本文-平芜编程栈

一、ROS2 简介与版本选择

1.1 什么是 ROS2

ROS2（Robot Operating System 2）是 ROS 的第二代机器人操作系统框架，由 Open Robotics 主导开发。与 ROS1 相比，ROS2 基于DDS（Data Distribution Service）通信中间件，解决了 ROS1 单点故障、实时性差、跨平台能力弱等问题，具备以下核心特性：

分布式通信：基于 DDS，支持多机、多机器人协作，无中心节点，天然支持 QOS 服务质量策略；
实时性支持：可运行在实时内核上，满足工业级控制需求；
跨平台：支持 Linux、Windows、macOS 以及嵌入式 RTOS；
安全性：内置 SROS2 安全机制，支持加密与权限控制；
生命周期管理：节点可配置 managed 状态机，便于系统级管理。

1.2 如何选择版本

ROS2 采用代号 + 发行时间的命名方式，每两年发布一个LTS（长期支持）版本，非 LTS 版本支持约 6 个月。新手与生产环境一律优先选择 LTS 版本。

版本代号	对应 Ubuntu	支持级别	支持截止
Humble Hawksbill	22.04 (Jammy)	LTS	2027 年 5 月
Jazzy Jalisco	24.04 (Noble)	LTS	2029 年 5 月
Foxy Fitzroy	20.04 (Focal)	LTS（已 EOL）	2023 年 5 月
Iron Irwini	22.04 (Jammy)	非 LTS	2024 年 11 月
Rolling Ridley	滚动更新	开发版	持续滚动

选型建议：截止 2026 年，Ubuntu 22.04 用户选 Humble、Ubuntu 24.04 用户选 Jazzy是最稳妥的组合；教程类学习资料以 Humble 最丰富，本文以 Humble 为例。

二、环境准备：Ubuntu 与 ROS2 版本对应关系

2.1 版本对应关系速查

ROS2 官方仅针对特定 Ubuntu LTS 版本发布二进制包，版本不对应会导致软件源失效或依赖冲突：

ROS2 版本	官方支持的 Ubuntu	内核建议
Humble	22.04 (Jammy)	5.15+
Jazzy	24.04 (Noble)	6.8
Foxy	20.04 (Focal)	5.4+
Rolling	24.04 (Noble)	6.8

注意：较新版本（如 Jazzy）在较旧 Ubuntu 上可能因 GLIBC 版本过低而无法运行；反之亦然。

2.2 检查系统版本

打开终端，执行：

lsb_release -a

输出中 Release 一行即为系统版本号。确认是 22.04 后继续。

2.3 安装方式选择

安装方式	适合场景	优缺点
二进制包（apt）	绝大多数用户	安装快、易卸载，本文推荐
源码编译	深度定制、ARM 移植	耗时长（数小时），依赖 colcon
Docker 镜像	隔离环境、快速试用	与宿主机隔离，需要掌握 Docker

三、完整安装步骤

以下以Ubuntu 22.04 + ROS2 Humble Desktop 完整版为例，全程使用 apt 二进制安装。

3.1 第一步：配置系统 locale（可选但推荐）

ROS2 对 UTF-8 支持依赖系统 locale，配置不当会出现中文乱码或 Invalid locale 警告：

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

国内用户若使用中文 locale（zh_CN.UTF-8）多数场景也能正常工作，但为减少未知问题，建议按官方文档设置为 en_US.UTF-8。

3.2 第二步：添加 ROS2 apt 软件源

3.2.1 安装基础工具

sudo apt update sudo apt install -y software-properties-common curl gnupg lsb-release

3.2.2 添加 ROS2 官方 GPG 密钥（国内用户推荐用镜像替代）

sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \ -o /usr/share/keyrings/ros-archive-keyring.gpg 国内 sudo curl -sSL https://mirrors.tuna.tsinghua.edu.cn/github-raw/ros/rosdistro/master/ros.asc -o /usr/share/keyrings/ros-archive-keyring.gpg

若 raw.githubusercontent.com 无法访问，使用国内镜像（国内网络常见）。

3.2.3 添加软件源（官方源 + 清华镜像加速）

将 ROS2 仓库写入 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

国内用户强烈建议配置镜像加速。以清华 TUNA 镜像为例，将上述命令中的域名替换为镜像地址：

# 方案 A：使用清华镜像源（国内首选） echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null # 方案 B：使用阿里云镜像源 # echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.aliyun.com/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

关键细节：镜像源的 GPG 密钥通常与官方一致。若镜像源报 NO_PUBKEY，可在 3.2.2 成功添加官方密钥后，再写入镜像源地址即可；密钥文件只需存在一次，signed-by 指向同一文件。

3.3 第三步：更新软件源并安装 ROS2

sudo apt update sudo apt upgrade -y

upgrade 会升级系统已有软件包，若担心影响现有环境可跳过，仅执行 apt update。

安装完整桌面版（含 rviz2、demo、教程示例等，新手推荐）：

sudo apt install -y ros-humble-desktop

若磁盘空间有限或仅需基础通信功能，可安装精简版：

sudo apt install -y ros-humble-ros-base

再安装常用的开发与调试工具：

sudo apt install -y ros-dev-tools python3-colcon-common-extensions python3-rosdep

安装耗时提示：ros-humble-desktop 包含数百个包，完整下载约 2~4 GB，取决于网络速度，属正常现象。国内用户务必确认已配置镜像源，否则可能数小时无法完成。

3.4 第四步：配置环境变量

ROS2 的环境变量通过 source 脚本注入，每个新终端都需要执行一次，否则会报 command not found: ros2。

临时生效（当前终端）：

source /opt/ros/humble/setup.bash

永久生效（推荐，写入 shell 配置）：

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

若使用 zsh，则写入 ~/.zshrc：echo "source /opt/ros/humble/setup.bash" >> ~/.zshrc。

验证环境变量是否配置成功：

printenv | grep ROS

能看到 ROS_DISTRO=humble 即说明环境生效。

四、验证测试：跑通第一个话题通信

4.1 验证 ros2 命令可用

ros2 --help

输出命令帮助列表即安装成功。

4.2 跑通 C++ 话题通信示例（talker / listener）

打开两个终端（均需已 source 环境）：

终端 1 —— 启动发布者：

ros2 run demo_nodes_cpp talker

终端 2 —— 启动订阅者：

ros2 run demo_nodes_cpp listener

终端 1 持续输出 Publishing: 'Hello World: N'、终端 2 持续输出 I heard: [Hello World: N]，说明 ROS2 通信链路完全正常。

4.3 使用 rqt_graph 查看节点关系（桌面版）

新开终端：

rqt_graph

可视化界面中能看到 /talker 与 /listener 两个节点通过 /chatter 话题相连，即安装验证完毕。

五、常见问题与解决方案

5.1 软件源 / 网络类问题

Q1：添加 GPG 密钥失败，raw.githubusercontent.com 无法连接

原因：GitHub 部分域名在国内网络环境不可达。
解决：直接跳过官方密钥步骤，改用镜像源地址（清华 / 阿里），多数镜像源下载软件包时不额外校验该密钥；若 apt 仍报 NO_PUBKEY，可先通过代理或浏览器手动下载 ros.key 文件，再复制到 /usr/share/keyrings/ 并设置权限：

sudo cp ~/Downloads/ros.key /usr/share/keyrings/ros-archive-keyring.gpg sudo chown root:root /usr/share/keyrings/ros-archive-keyring.gpg sudo chmod 644 /usr/share/keyrings/ros-archive-keyring.gpg

Q2：apt update 极慢或卡死

原因：默认使用官方源 packages.ros.org，国内访问慢。
解决：改用清华 / 阿里镜像（见 3.2.3），并重新 sudo apt update。也可同时将 Ubuntu 系统源替换为国内镜像（阿里云、清华），整体提速。

Q3：apt update 报 E: Conflicting distribution 或签名错误

原因：$(lsb_release -cs) 展开的代号与镜像目录不匹配，或残留了错误的源配置。

解决：

lsb_release -cs # 确认输出应为 jammy # 清理错误源后重新写入正确源 sudo rm -f /etc/apt/sources.list.d/ros2.list sudo apt update

再按 3.2.3 重新写入。

Q4：apt update 报 The repository ... does not have a Release file

原因：镜像目录中不存在当前 Ubuntu 代号对应的 ROS2 目录（例如在 Ubuntu 20.04 上配置了 Humble 源）。
解决：核对 Ubuntu 与 ROS2 版本对应表（见 2.1），换成匹配组合，或改用支持该系统的版本（如 20.04 用 Foxy 源）。

5.2 依赖冲突类问题

Q5：安装时提示依赖关系问题，仍未被配置 / E: Unmet dependencies

原因：系统中存在损坏的软件包或旧的 ROS1 残留。

解决：

# 尝试修复损坏依赖 sudo apt --fix-broken install sudo apt update && sudo apt upgrade -y

若因 ROS1（ROS Noetic 等）残留导致冲突，需先移除 ROS1 相关包再安装 ROS2：

sudo apt remove 'ros-*' # 谨慎：会删除所有 ROS 包

Q6：ros-humble-desktop 安装报 Unable to locate package

原因：ROS2 源未添加成功，或 apt update 未执行。
解决：确认 3.2 步骤的源文件已写入且 sudo apt update 无报错，再重新安装。

5.3 找不到命令类问题

Q7：执行 ros2 提示 command not found: ros2

原因：环境变量未 source，或未安装对应软件包。

解决：

# 先确认包是否安装 dpkg -l | grep ros-humble-desktop # 若已安装则 source 环境 source /opt/ros/humble/setup.bash

若 dpkg -l 无输出，说明未安装成功，回到 3.3 重新安装。

Q8：ros2 run 提示 Package 'xxx' not found

原因：功能包未安装，或该包在 ros-humble-ros-base 精简版中不存在。

解决：按需安装对应包，如：

sudo apt install -y ros-humble-demo-nodes-cpp

Q9：colcon 提示 command not found

原因：未安装 colcon 扩展包。

解决：

sudo apt install -y python3-colcon-common-extensions

5.4 环境变量未生效类问题

Q10：source 后当前终端正常，新开终端又失效

原因：source 只对当前 shell 生效，未写入 ~/.bashrc。
解决：执行一次 echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc 后 source ~/.bashrc，之后所有新终端自动生效。

Q11：printenv | grep ROS 无输出

原因：source 的路径写错（如拼成 /opt/ros/humble/setup.bash 的版本号不对），或安装的是 Jazzy 却 source 了 humble。
解决：ls /opt/ros/ 查看实际安装的版本目录，按实际目录名 source。

5.5 colcon 编译报错类问题

Q12：colcon build 报 ModuleNotFoundError: No module named 'catkin_pkg' 等 Python 模块缺失

原因：缺少 Python 依赖。

解决：

pip install catkin_pkg empy lark # 或按报错模块名安装 # 部分系统需使用 pip3 或加 --user pip3 install --user catkin_pkg empy lark

Q13：colcon build 报 ament_cmake 相关错误 / Could not find a package configuration file

原因：工作空间缺少依赖包（如只装了 ros-base 未装 ros-dev-tools 或缺少特定依赖）。

解决：

sudo apt install -y ros-dev-tools sudo apt install -y ros-humble-<缺失的依赖包名> # 若无法确定，可在 src 目录使用 rosdep 自动解析依赖 sudo rosdep init rosdep update rosdep install --from-paths src -y --ignore-src

Q14：colcon build 卡在某个包或内存不足

原因：串行编译大工程耗时，或系统内存不足。
解决：使用并行编译：
```
colcon build --parallel-workers 4
```
只编译单个包：colcon build --packages-select <包名>；清理重编：删除 build/ install/ log/ 目录后重新 colcon build。

5.6 权限类问题

Q15：操作 /opt/ros 下文件提示 Permission denied

原因：ROS2 系统文件归 root 所有，普通用户无权修改。
解决：不要直接修改 /opt/ros。用户自己的工作空间建在 ~/ros2_ws 下，使用普通权限即可；需要系统级操作时使用 sudo。

Q16：sudo rosdep init 提示已存在 / 无法写入 /etc/ros

原因：已执行过 rosdep init，或权限不足。
解决：已初始化则跳过该步直接 rosdep update；权限问题用 sudo 执行即可。

Q17：在共享服务器 / 容器中 source /opt/ros/... 提示权限或脚本不存在

原因：ROS2 未真正安装到 /opt/ros，或使用 Docker 挂载导致路径缺失。
解决：ls /opt/ros 确认目录；Docker 环境需在镜像内执行安装步骤，而非宿主机挂载目录。

5.7 其他常见问题

Q18：rviz2 启动报 QXcbConnection: Could not connect to display

原因：无图形界面（纯 SSH / 无显示器环境）。
解决：需要图形界面时配置 X11 转发（SSH 加 -X 参数），或使用 Docker 的 GUI 方案；仅需通信验证时使用无界面命令。

Q19：运行示例时终端报 Failed to create timer 或 DDS 相关 warning

原因：多数为 DDS 自动发现延迟或环境变量缺失，属于低危告警。
解决：设置 export RMW_IMPLEMENTATION=rmw_fastrtps_cpp（默认实现），或 export ROS_DOMAIN_ID=1（多机通信时需统一 domain ID），一般不影响功能。

六、总结

ROS2 安装的整体流程可归纳为五步：确认系统版本 → 配置软件源（含镜像加速）→ apt 安装 → source 环境变量 → 跑通 demo 验证。要点如下：

版本必须匹配：Ubuntu 22.04 → Humble，Ubuntu 24.04 → Jazzy，选 LTS 最稳；
国内必须配镜像：清华 / 阿里镜像可避免绝大多数网络问题；
环境变量写入 ~/.bashrc：避免每次开终端都要手动 source；
遇到问题先查日志：apt 报错看源配置，colcon 报错看依赖，ros2 找不到看环境变量，绝大多数问题都能在上文对应小节找到答案。

安装完成后，建议从 ros2 run demo_nodes_cpp talker 开始体验 ROS2 的话题通信，再逐步学习 rclcpp 编程与 colcon 工作空间管理。

ROS2 安装完全指南（Ubuntu 版）：从零开始到跑通第一个节点本文