ROS2教程 第01篇：为什么装了ROS2跑不起来

"跟着教程一步步装，结果一运行就报错……"

本文总结了ROS2环境搭建中的常见问题和解决方案。

常见问题

以下是ROS2安装过程中常见的报错信息：

E: Unable to locate package ros-humble-desktop

ros2: command not found

RLException: Unable to communicate with master!

ImportError: No module named 'rclpy'

下面逐一说明解决方法。

Ubuntu与ROS2版本对应关系

版本不匹配是安装失败的最常见原因。ROS2和Ubuntu版本是严格绑定的。

版本选择建议：

• • 新手或企业项目：选择 Humble（22.04），生态成熟，教程丰富
• • 新项目或需要新特性：选择 Jazzy（24.04）
• • 注意：Ubuntu 20.04不支持Humble，Ubuntu 22.04不支持Jazzy

完整安装步骤（以Ubuntu 22.04 + Humble为例）

第一步：设置Locale

ROS2要求系统支持UTF-8编码：

# 检查当前localelocale# 如果没有en_US.UTF-8，需要安装并设置sudo apt update && sudo apt install localessudo locale-gen en_US en_US.UTF-8sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8export LANG=en_US.UTF-8# 验证locale

第二步：添加ROS2软件源

# 1. 确保安装了curl和gnupgsudo apt update && sudo apt install curl gnupg lsb-release -y# 2. 添加ROS2的GPG密钥sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \    -o /usr/share/keyrings/ros-archive-keyring.gpg# 3. 添加软件源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" \    | sudotee /etc/apt/sources.list.d/ros2.list > /dev/null

注意： 如果你使用的是国内网络，建议添加清华镜像源加速：

# 替换为清华源echo"deb [arch=$(dpkg --print-architecture) \ signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] \ https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" \ | sudotee /etc/apt/sources.list.d/ros2.list > /dev/null

第三步：安装ROS2

# 更新软件源（添加新源后必须执行）sudo apt update# 安装ROS2桌面完整版（包含RViz、Gazebo等可视化工具）sudo apt install ros-humble-desktop -y# 如果你只需要命令行工具（服务器/嵌入式设备推荐）# sudo apt install ros-humble-ros-base -y# 安装开发工具（colcon构建工具、rosdep依赖管理）sudo apt install python3-colcon-common-extensions python3-rosdep -y

第四步：配置环境变量

每次打开新终端都需要source环境变量：

# 加载ROS2环境变量source /opt/ros/humble/setup.bash# 验证：如果能输出版本信息，说明安装成功ros2 --version

可以将source命令添加到 .bashrc 中，避免每次手动执行：

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

验证安装

安装完成后，使用官方Demo验证环境：

# 终端1：启动发布者节点ros2 run demo_nodes_cpp talker

# 终端2：启动订阅者节点ros2 run demo_nodes_cpp listener

如果终端2能持续打印终端1发出的消息，说明ROS2环境搭建成功。

[图片：talker和listener终端运行截图，展示消息传递效果]

ros2 doctor诊断工具

ROS2自带的诊断工具，用于快速定位环境问题：

# 基础检查ros2 doctor# 详细报告（推荐）ros2 doctor --report# 检查特定模块ros2 doctor --report-verbose

常见诊断结果说明：

常见问题排查清单

问题排查对照表：

多版本共存：Overlay机制

需要同时安装多个ROS2版本时（如维护不同项目），ROS2通过Overlay机制实现。

核心原理

ROS2的环境变量采用后加载覆盖先加载的机制。每次执行source setup.bash，新的路径会被加到环境变量最前面。

# 底层：系统安装的Humblesource /opt/ros/humble/setup.bash# 覆盖层：工作空间的Humble（优先级更高）source ~/ros2_ws/install/setup.bash

最后source的环境配置优先级最高。

多版本切换技巧

# 创建别名，快速切换版本echo'alias humble="source /opt/ros/humble/setup.bash"' >> ~/.bashrcecho'alias jazzy="source /opt/ros/jazzy/setup.bash"' >> ~/.bashrcsource ~/.bashrc# 使用时直接输入humble   # 切换到Humble环境jazzy    # 切换到Jazzy环境

不要在同一个终端中同时source两个不同版本的ROS2环境，会导致冲突。

查看当前环境

# 查看当前ROS2版本printenv ROS_DISTRO# 查看所有ROS相关的环境变量printenv | grep ROS

rosdep依赖管理工具

rosdep是ROS2官方的依赖管理工具：

# 首次使用需要初始化sudo rosdep initrosdep update# 安装工作空间中所有包的依赖cd ~/ros2_wsrosdep install --from-paths src --ignore-src -y

国内用户注意：rosdep update可能因网络问题失败，可以使用国内镜像：

export ROSDISTRO_INDEX_URL=https://mirrors.tuna.tsinghua.edu.cn/rosdistro/index-v4.yamlrosdep update

环境搭建检查清单

搭建新环境时按以下清单检查：

• • 确认Ubuntu版本与ROS2发行版匹配
• • 设置UTF-8 locale
• • 添加ROS2软件源（国内用户用镜像）
• • 执行 sudo apt update
• • 安装 ros-xxx-desktop 或 ros-xxx-ros-base
• • 安装开发工具（colcon、rosdep）
• • Source环境变量（或写入.bashrc）
• • 运行 ros2 run demo_nodes_cpp talker 验证
• • 运行 ros2 doctor 做全面检查