Ubuntu 24.04 安装 ROS2 Jazzy 完整版

qq_28312849

9人浏览 · 2026-08-03 17:22:58

qq_28312849 · 2026-08-03 17:22:58 发布

适配系统：Ubuntu24.04 LTS (Noble Numbat)

ROS2版本：Jazzy Jalisco（LTS长期支持版）

文档说明：优化原生安装流程，修复国内网络超时、密钥失效等常见问题，完整包含环境配置、编译工具、工作空间创建、报错修复全流程，新手可直接复制命令操作。

一、前言

ROS2 Jazzy 是 Ubuntu24.04 官方适配的 LTS 机器人开发框架，原生支持 SLAM 建图、Nav2 导航、MoveIt2 机械臂控制、Gazebo Harmonic 仿真及各类传感器数据处理，适用于课程实验、AGV 小车、机械臂、无人机仿真开发场景。

核心适配规则

仅支持 Ubuntu24.04，Ubuntu22.04 需安装 Humble 版本，禁止混用
支持 WSL2 安装，GUI 工具（RViz/Gazebo）需额外配置图形转发
安装前建议将 Ubuntu 软件源更换为清华/中科大国内源，保障网络稳定

二、系统前置准备

1. 更新系统软件源与依赖

sudo apt update sudo apt upgrade -y

2. 校验系统版本

lsb_release -a

输出结果必须包含：Ubuntu 24.04 LTS (Noble Numbat)，版本不符请停止安装。

三、ROS2 Jazzy 正式安装流程

1. 开启 universe 软件源

ROS2 大部分依赖依赖该软件源，必须开启

sudo add-apt-repository universe sudo apt update

2. 安装基础依赖工具

sudo apt install curl gnupg lsb-release -y

3. 添加 ROS2 官方 GPG 密钥

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

4. 添加 ROS2 软件源

Ubuntu24.04 废弃 apt-key 命令，使用新版密钥绑定方式，直接复制整条命令执行

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

刷新软件源缓存

sudo apt update

5. 安装 ROS2 核心版本

根据开发需求选择对应版本，仿真开发优先完整版

版本1：Desktop 版（算法调试、日常开发）

sudo apt install ros-jazzy-desktop -y

版本2：Desktop-Full 完整版（仿真、导航、机械臂开发推荐）

sudo apt install ros-jazzy-desktop-full -y

四、环境变量配置（解决 command not found 核心）

根据终端类型选择对应配置，Ubuntu 默认终端为 bash

1. bash 终端（系统默认）

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

2. zsh 终端（自定义终端）

echo"source /opt/ros/jazzy/setup.zsh" >> ~/.zshrc source ~/.zshrc

临时生效命令（当前终端有效，关闭失效）：source /opt/ros/jazzy/setup.bash

五、安装验证（必做步骤）

1. 校验核心功能包

ros2 pkg list | grep demo

输出 demo_nodes_cpp、demo_nodes_py 说明功能包完整

2. 双向通信测试（核心功能验证）

终端1（发布者）

ros2 run demo_nodes_cpp talker

终端2（订阅者）

ros2 run demo_nodes_cpp listener

订阅终端持续打印 Hello World 数据流，代表 ROS2 通信环境正常

可选小乌龟测试

ros2 run turtlesim turtlesim_node

六、安装 colcon 编译工具 + 创建工作空间

ROS2 使用 colcon 编译工具，替代 ROS1 catkin，是自定义功能包开发必备工具

1. 安装编译工具与扩展

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

2. 初始化 rosdep（仅首次安装执行）

sudo rosdep init

3. 创建标准工作空间

mkdir -p ~/ros2_ws/src cd ~/ros2_ws colcon build --symlink-install

编译完成后加载工作空间环境

source install/setup.bash

开机自动加载工作空间（可选）

echo"source ~/ros2_ws/install/setup.bash" >> ~/.bashrc

七、ROS2 版本功能对比

版本类型	包含功能	适用场景
ros-jazzy-ros-base	最小核心库，无GUI界面	服务器部署、纯后台算法运行
ros-jazzy-desktop	核心库+ RViz2、rqt调试工具、小乌龟示例	日常开发、算法调试、无仿真需求场景
ros-jazzy-desktop-full	desktop 全部功能+ Gazebo Harmonic仿真、Nav2导航、点云感知库、机械臂依赖	仿真开发、导航、机械臂、机器人全功能开发

八、ROS2 完整卸载命令

sudo apt remove ros-jazzy-* -y sudo apt autoremove -y sudorm -f /etc/apt/sources.list.d/ros2.list

卸载完成后，手动删除 .bashrc/.zshrc 中 ROS2 环境变量配置行，避免冲突。

九、国内高频报错汇总与修复

报错1：curl 下载 ros.key 超时、raw.githubusercontent 连接失败

解决方案：放弃官方原链接，全程使用文档中 ghproxy 国内加速链接 下载密钥。

报错2：apt update 提示 NO_PUBKEY 公钥错误

原因：本地密钥损坏或不匹配，重新下载密钥即可

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

报错3：ros2: command not found

临时修复：当前终端执行 source /opt/ros/jazzy/setup.bash
永久修复：检查 bash/zsh 配置文件是否写入环境变量
校验安装：ls /opt/ros/jazzy，无文件夹则说明安装失败，需重新安装

报错4：apt 软件源重复、源冲突

查看所有 ROS 相关源文件

ls /etc/apt/sources.list.d/

删除旧版本冗余源文件

sudorm /etc/apt/sources.list.d/ros-latest.list sudo apt update

报错5：rosdep update 超时失败（国内经典问题）

替换 rosdep 数据源为国内镜像

sudo sed -i 's/raw.githubusercontent.com/ghproxy.com\/https:\/\/raw.githubusercontent.com/g' /etc/ros/rosdep/sources.list.d/20-default.list rosdep update

十、新手使用核心注意事项

环境加载顺序：先加载系统 ROS2 环境，再加载自定义工作空间环境，顺序颠倒会引发未知报错。
编译内存问题：设备内存不足导致 colcon 编译失败，使用串行编译命令降低内存占用：colcon build --executor sequential
仿真器版本区分：Jazzy 配套仿真器为 Gazebo Harmonic，不兼容旧版 Gazebo11，禁止混用安装。
多版本冲突：同一系统不要同时安装 Jazzy、Humble 等多个 ROS2 版本，会造成环境彻底冲突。
配置生效规则：修改 .bashrc/.zshrc 配置后，需重新打开终端或手动 source 方可生效。