一、ROS2 简介与版本选择1.1 什么是 ROS2ROS2Robot Operating System 2是 ROS 的第二代机器人操作系统框架由 Open Robotics 主导开发。与 ROS1 相比ROS2 基于DDSData Distribution Service通信中间件解决了 ROS1 单点故障、实时性差、跨平台能力弱等问题具备以下核心特性分布式通信基于 DDS支持多机、多机器人协作无中心节点天然支持 QOS 服务质量策略实时性支持可运行在实时内核上满足工业级控制需求跨平台支持 Linux、Windows、macOS 以及嵌入式 RTOS安全性内置 SROS2 安全机制支持加密与权限控制生命周期管理节点可配置 managed 状态机便于系统级管理。1.2 如何选择版本ROS2 采用代号 发行时间的命名方式每两年发布一个LTS长期支持版本非 LTS 版本支持约 6 个月。新手与生产环境一律优先选择 LTS 版本。版本代号对应 Ubuntu支持级别支持截止Humble Hawksbill22.04 (Jammy)LTS2027 年 5 月Jazzy Jalisco24.04 (Noble)LTS2029 年 5 月Foxy Fitzroy20.04 (Focal)LTS已 EOL2023 年 5 月Iron Irwini22.04 (Jammy)非 LTS2024 年 11 月Rolling Ridley滚动更新开发版持续滚动选型建议截止 2026 年Ubuntu 22.04 用户选 Humble、Ubuntu 24.04 用户选 Jazzy是最稳妥的组合教程类学习资料以 Humble 最丰富本文以 Humble 为例。二、环境准备Ubuntu 与 ROS2 版本对应关系2.1 版本对应关系速查ROS2 官方仅针对特定 Ubuntu LTS 版本发布二进制包版本不对应会导致软件源失效或依赖冲突ROS2 版本官方支持的 Ubuntu内核建议Humble22.04 (Jammy)5.15Jazzy24.04 (Noble)6.8Foxy20.04 (Focal)5.4Rolling24.04 (Noble)6.8注意较新版本如 Jazzy在较旧 Ubuntu 上可能因 GLIBC 版本过低而无法运行反之亦然。2.2 检查系统版本打开终端执行lsb_release -a输出中 Release 一行即为系统版本号。确认是 22.04 后继续。2.3 安装方式选择安装方式适合场景优缺点二进制包apt绝大多数用户安装快、易卸载本文推荐源码编译深度定制、ARM 移植耗时长数小时依赖 colconDocker 镜像隔离环境、快速试用与宿主机隔离需要掌握 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_ALLen_US.UTF-8 LANGen_US.UTF-8 export LANGen_US.UTF-8国内用户若使用中文 localezh_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-release3.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 第三步更新软件源并安装 ROS2sudo apt update sudo apt upgrade -yupgrade 会升级系统已有软件包若担心影响现有环境可跳过仅执行 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则写入 ~/.zshrcecho source /opt/ros/humble/setup.bash ~/.zshrc。验证环境变量是否配置成功printenv | grep ROS能看到 ROS_DISTROhumble 即说明环境生效。四、验证测试跑通第一个话题通信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.gpgQ2apt update 极慢或卡死原因默认使用官方源 packages.ros.org国内访问慢。解决改用清华 / 阿里镜像见 3.2.3并重新 sudo apt update。也可同时将 Ubuntu 系统源替换为国内镜像阿里云、清华整体提速。Q3apt 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 重新写入。Q4apt 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若因 ROS1ROS Noetic 等残留导致冲突需先移除 ROS1 相关包再安装 ROS2sudo apt remove ros-* # 谨慎会删除所有 ROS 包Q6ros-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 重新安装。Q8ros2 run 提示 Package xxx not found原因功能包未安装或该包在 ros-humble-ros-base 精简版中不存在。解决按需安装对应包如sudo apt install -y ros-humble-demo-nodes-cppQ9colcon 提示 command not found原因未安装 colcon 扩展包。解决sudo apt install -y python3-colcon-common-extensions5.4 环境变量未生效类问题Q10source 后当前终端正常新开终端又失效原因source 只对当前 shell 生效未写入 ~/.bashrc。解决执行一次 echo source /opt/ros/humble/setup.bash ~/.bashrc 后 source ~/.bashrc之后所有新终端自动生效。Q11printenv | grep ROS 无输出原因source 的路径写错如拼成 /opt/ros/humble/setup.bash 的版本号不对或安装的是 Jazzy 却 source 了 humble。解决ls /opt/ros/ 查看实际安装的版本目录按实际目录名 source。5.5 colcon 编译报错类问题Q12colcon build 报 ModuleNotFoundError: No module named catkin_pkg 等 Python 模块缺失原因缺少 Python 依赖。解决pip install catkin_pkg empy lark # 或按报错模块名安装 # 部分系统需使用 pip3 或加 --user pip3 install --user catkin_pkg empy larkQ13colcon 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-srcQ14colcon 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。Q16sudo rosdep init 提示已存在 / 无法写入 /etc/ros原因已执行过 rosdep init或权限不足。解决已初始化则跳过该步直接 rosdep update权限问题用 sudo 执行即可。Q17在共享服务器 / 容器中 source /opt/ros/... 提示权限或脚本不存在原因ROS2 未真正安装到 /opt/ros或使用 Docker 挂载导致路径缺失。解决ls /opt/ros 确认目录Docker 环境需在镜像内执行安装步骤而非宿主机挂载目录。5.7 其他常见问题Q18rviz2 启动报 QXcbConnection: Could not connect to display原因无图形界面纯 SSH / 无显示器环境。解决需要图形界面时配置 X11 转发SSH 加 -X 参数或使用 Docker 的 GUI 方案仅需通信验证时使用无界面命令。Q19运行示例时终端报 Failed to create timer 或 DDS 相关 warning原因多数为 DDS 自动发现延迟或环境变量缺失属于低危告警。解决设置 export RMW_IMPLEMENTATIONrmw_fastrtps_cpp默认实现或 export ROS_DOMAIN_ID1多机通信时需统一 domain ID一般不影响功能。六、总结ROS2 安装的整体流程可归纳为五步确认系统版本 → 配置软件源含镜像加速→ apt 安装 → source 环境变量 → 跑通 demo 验证。要点如下版本必须匹配Ubuntu 22.04 → HumbleUbuntu 24.04 → Jazzy选 LTS 最稳国内必须配镜像清华 / 阿里镜像可避免绝大多数网络问题环境变量写入 ~/.bashrc避免每次开终端都要手动 source遇到问题先查日志apt 报错看源配置colcon 报错看依赖ros2 找不到看环境变量绝大多数问题都能在上文对应小节找到答案。安装完成后建议从 ros2 run demo_nodes_cpp talker 开始体验 ROS2 的话题通信再逐步学习 rclcpp 编程与 colcon 工作空间管理。