ros2权威指南，人工智能自行开发机器人提示词数据和流程，供大模型检索使用，非人类观看文档

本文档是

章节 内容
1. 系统要求 Ubuntu 版本与 ROS2 版本对应关系表
2. 字符编码 locale 配置避免乱码
3. 清华镜像源 GPG 密钥导入 + apt 源写入（逐条命令）
4. 安装 desktop-full 三种安装包对比 + 安装命令
5. 配套工具 colcon、robot-state-publisher、joint-state-publisher 等
6. 环境变量 bashrc 永久配置
7. 安装验证 rviz2、gz sim、colcon 路径和包数量检查
8. Demo 测试 talker/listener、turtlesim、话题查看
9. 常见问题 5 个常见错误的原因和解决方案
10. 命令速查表 节点、话题、编译、工具等常用命令一览

ROS2 Jazzy Desktop-Full 安装部署指南

适用系统: Ubuntu 24.04 LTS (Noble Numbat) x86_64
ROS2 版本: Jazzy Jalisco
镜像源: 清华大学 TUNA 镜像
最后验证日期: 2026-06-12

目录

  1. 系统要求与版本对应
  2. Step 1: 配置系统字符编码
  3. Step 2: 配置清华 ROS2 镜像源
  4. Step 3: 安装 ROS2 Desktop-Full
  5. Step 4: 安装编译与仿真配套工具
  6. Step 5: 配置环境变量（永久生效）
  7. Step 6: 安装验证
  8. Step 7: 运行 Demo 测试
  9. 常见问题与注意事项
  10. 常用命令速查表

1. 系统要求与版本对应

⚠️ 重要：Ubuntu 版本必须与 ROS2 版本匹配

Ubuntu 版本 代号 对应 ROS2 版本
22.04 LTS Jammy Humble Hawksbill
24.04 LTS Noble Jazzy Jalisco

本文档基于 Ubuntu 24.04 → ROS2 Jazzy，如果你的系统是 22.04，请将文中所有 jazzy 替换为 humble。

检查系统版本

lsb_release -a
# 输出应显示: Ubuntu 24.04.x LTS, Codename: noble

uname -m
# 输出应为: x86_64 (64位系统)

2. Step 1: 配置系统字符编码

避免后续编译和终端出现乱码问题。

# 安装 locale 工具
sudo apt update && sudo apt install -y locales

# 生成 UTF-8 编码
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

验证:

echo $LANG
# 应输出: en_US.UTF-8

3. Step 2: 配置清华 ROS2 镜像源

3.1 安装源管理依赖工具

sudo apt install -y curl gnupg lsb-release

3.2 通过清华镜像导入 ROS GPG 密钥

sudo curl -sSL https://mirrors.tuna.tsinghua.edu.cn/rosdistro/ros.key \
    -o /usr/share/keyrings/ros-archive-keyring.gpg

3.3 写入 ROS2 apt 源

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

验证源文件:

cat /etc/apt/sources.list.d/ros2.list
# 应输出: deb [arch=amd64 signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu noble main

3.4 更新 apt 索引

sudo apt update

✅ 如果输出中出现 https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu noble InRelease 说明源配置成功。

4. Step 3: 安装 ROS2 Desktop-Full

安装包说明

包名 内容
ros-jazzy-ros-base 核心通信库（最小安装）
ros-jazzy-desktop 基础 + RViz2 + rqt + turtlesim
ros-jazzy-desktop-full 全部包含 + Gazebo Sim + 导航 + 视觉 + 点云 ✓ 推荐

安装命令

# 安装完整版（约 3-5 GB，预计 15-40 分钟）
sudo apt install -y ros-jazzy-desktop-full

⏳ 这是最大的安装包，包含以下全部组件:

  • RViz2 — 3D 可视化工具
  • Gazebo Sim — 物理仿真环境
  • rqt — 图形化调试工具集
  • rosbag2 — 数据录制/回放
  • navigation2 — 导航框架
  • perception_pcl — 点云处理
  • turtlesim — 入门教学仿真

5. Step 4: 安装编译与仿真配套工具

# colcon: ROS2 官方编译工具
sudo apt install -y python3-colcon-common-extensions

# 机器人建模必需工具
sudo apt install -y \
    ros-jazzy-robot-state-publisher \
    ros-jazzy-joint-state-publisher-gui

# Demo 示例节点（用于测试）
sudo apt install -y \
    ros-jazzy-demo-nodes-cpp \
    ros-jazzy-demo-nodes-py

# rqt 常用插件
sudo apt install -y ros-jazzy-rqt-common-plugins

6. Step 5: 配置环境变量（永久生效）

# 写入 bashrc，新终端自动加载 ROS2 环境
echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc

# 当前终端立即生效
source ~/.bashrc

验证:

# 检查 ROS2 CLI 是否可用
ros2 --help

# 查看已安装的 ROS2 包数量
ros2 pkg list | wc -l
# desktop-full 应有 300+ 个包

💡 如果使用 zsh，替换为:

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

7. Step 6: 安装验证

7.1 验证核心可执行文件

which rviz2    # 应输出: /opt/ros/jazzy/bin/rviz2
which gz       # 应输出: /opt/ros/jazzy/opt/gz_tools_vendor/bin/gz
which colcon   # 应输出: /usr/bin/colcon

7.2 验证核心功能包

ros2 pkg list | grep -E "rviz|ros_gz|rqt|robot_state|joint_state"

应能看到:

  • rviz2, rviz_common, rviz_default_plugins — RViz2 可视化
  • ros_gz_sim, ros_gz_bridge — Gazebo Sim 仿真
  • rqt_common_plugins, rqt_graph, rqt_bag — rqt 工具
  • robot_state_publisher — 机器人状态发布
  • joint_state_publisher_gui — 关节可视化

7.3 启动 RViz2（图形界面验证）

rviz2

✅ 如果弹出 3D 可视化窗口，说明安装成功。关闭窗口继续下一步。

7.4 启动 Gazebo Sim（仿真环境验证）

gz sim

✅ 如果弹出 Gazebo 仿真窗口，说明仿真环境安装成功。

8. Step 7: 运行 Demo 测试

8.1 Talker / Listener 通信测试

打开两个终端（都要先 source 环境）:

终端 1 — 发布端 (talker):

source /opt/ros/jazzy/setup.bash
ros2 run demo_nodes_py talker

输出示例:

[INFO] [talker]: Publishing: "Hello World: 0"
[INFO] [talker]: Publishing: "Hello World: 1"
[INFO] [talker]: Publishing: "Hello World: 2"
...

终端 2 — 订阅端 (listener):

source /opt/ros/jazzy/setup.bash
ros2 run demo_nodes_py listener

输出示例:

[INFO] [listener]: I heard: [Hello World: 0]
[INFO] [listener]: I heard: [Hello World: 1]
[INFO] [listener]: I heard: [Hello World: 2]
...

✅ 两端能互相通信说明 ROS2 核心功能正常。按 Ctrl+C 停止。

8.2 C++ 版 Demo（可选）

# 终端 1
ros2 run demo_nodes_cpp talker

# 终端 2
ros2 run demo_nodes_cpp listener

8.3 查看话题

在第三个终端执行:

ros2 topic list
# 应看到: /chatter, /parameter_events, /rosout 等

ros2 topic echo /chatter
# 实时查看 talker 发布的消息

8.4 Turtlesim 仿真（入门经典）

# 终端 1: 启动 turtlesim 窗口
ros2 run turtlesim turtlesim_node

# 终端 2: 启动键盘控制
ros2 run turtlesim turtle_teleop_key

✅ 按方向键控制小海龟移动，说明 ROS2 节点通信正常。

9. 常见问题与注意事项

❌ 问题 1: "Unable to locate package ros-jazzy-desktop"

原因: ROS2 apt 源未正确配置
解决:

# 重新导入密钥
sudo curl -sSL https://mirrors.tuna.tsinghua.edu.cn/rosdistro/ros.key \
    -o /usr/share/keyrings/ros-archive-keyring.gpg

# 重写源文件（注意替换 noble 为你的系统代号）
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu noble main" | \
    sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

sudo apt update

❌ 问题 2: "source /opt/ros/jazzy/setup.bash: 没有那个文件或目录"

原因: ROS2 未安装或安装失败
解决: 检查安装是否完成

dpkg -l | grep ros-jazzy | wc -l
# 如果为 0，说明未安装成功，重新执行安装命令

❌ 问题 3: RViz2 / Gazebo 启动无反应

原因: 没有图形显示环境（DISPLAY 未设置）
解决:

# 检查当前显示服务器
echo $DISPLAY
# 如果为空，说明 SSH 连接没有转发图形

# 如果是通过 SSH 连接，需要设置 DISPLAY
export DISPLAY=:0   # 或 :1，取决于 X11 运行在哪个 display

# 推荐: 直接在虚拟机控制台的终端中运行

❌ 问题 4: GPG 密钥错误 / NO_PUBKEY

# 删除旧密钥重新导入
sudo rm /usr/share/keyrings/ros-archive-keyring.gpg
sudo curl -sSL https://mirrors.tuna.tsinghua.edu.cn/rosdistro/ros.key \
    -o /usr/share/keyrings/ros-archive-keyring.gpg
sudo apt update

❌ 问题 5: sudo 密码提示导致脚本中断

原因: 在 echo "xxx" | sudo tee 这类命令中，sudo 没有通过 -S 接收密码
解决: 使用 sudo -S bash -c 包裹:

echo "123456" | sudo -S bash -c 'echo "内容" > /etc/apt/sources.list.d/ros2.list'

⚠️ 注意事项汇总

  1. 版本匹配: Ubuntu 24.04 必须用 ros-jazzy-*，不要用 ros-humble-*
  2. 磁盘空间: desktop-full 约需 5GB，确保磁盘有足够空间
  3. 网络: 使用清华镜像无需FQ，避免 GitHub 超时
  4. 环境变量: 每次开新终端需确保 source /opt/ros/jazzy/setup.bash 已执行
  5. VMware 用户: 建议开启 3D 加速，否则 RViz2/Gazebo 渲染可能卡顿
  6. 不要混装 ROS1: 本文档已剔除所有 ROS1 相关内容，不要同时安装 ROS1

10. 常用命令速查表

环境管理

source /opt/ros/jazzy/setup.bash    # 加载 ROS2 环境
ros2 --help                          # 查看帮助

包管理

ros2 pkg list                       # 列出所有已安装包
ros2 pkg list | wc -l               # 统计包数量
ros2 pkg prefix <包名>              # 查看包安装路径
sudo apt install ros-jazzy-<包名>   # 安装额外功能包

节点与话题

ros2 node list                      # 列出活跃节点
ros2 topic list                     # 列出所有话题
ros2 topic echo /chatter            # 实时查看话题内容
ros2 topic info /chatter            # 查看话题信息

运行节点

ros2 run <包名> <节点名>            # 运行节点
ros2 run demo_nodes_py talker       # Python demo 发布
ros2 run demo_nodes_py listener     # Python demo 订阅
ros2 run demo_nodes_cpp talker      # C++ demo 发布

启动工具

rviz2                               # RViz2 可视化
gz sim                              # Gazebo Sim 仿真
rqt                                 # rqt 图形工具集
rqt_graph                           # 节点关系图
rqt_console                         # 日志查看

编译工作空间

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws
colcon build                        # 编译
source install/setup.bash           # 加载编译结果

安装结果摘要

项目 值
ROS2 版本 Jazzy Jalisco
安装包 desktop-full
功能包数量 341 个
deb 包数量 348 个
镜像源 清华大学 TUNA
仿真环境 Gazebo Sim (新版)
可视化工具 RViz2
编译工具 colcon
磁盘占用 ~5 GB
环境变量 ~/.bashrc 自动加载

文档生成时间: 2026-06-12 | 基于 Ubuntu 24.04 + ROS2 Jazzy Desktop-Full 实际安装经验 供人工智能检索使，非人类观查文档

posted @ 2026-06-12 23:17  鬼门元歌  阅读(3)  评论(0)    收藏  举报