ROS 2 Jazzy 一键安装 + 跑通 turtlesim

为什么选 Jazzy (2024-2027)？

• LTS 5 年（到 2029 年 5 月）
• Python 3.12 + C++17 现代特性
• rclcpp / rclpy 同步 API 全面 GA
• ros2_control 3.x + Nav2 1.2 性能大幅提升
• zenoh_cpp 正式从实验毕业，推荐生产用 Zenoh（替代 DDS）

系统选择

平台	推荐度	备注
Ubuntu 24.04 LTS	⭐⭐⭐⭐⭐	一键 apt 安装，零坑
Debian 12 (Bookworm)	⭐⭐⭐⭐	ROS 2 官方支持，apt 源可用
树莓派 OS (64-bit)	⭐⭐⭐	性能受限，适合 RViz2 / 仿真
macOS Sonoma+	⭐⭐	仅命令行，rviz2 不可用
Windows 11 WSL2	⭐⭐⭐⭐	性能等同 Ubuntu，开发友好
Docker 容器	⭐⭐⭐⭐	隔离干净，CI 首选

方案 A：Ubuntu 24.04 / Debian 12 (推荐)

1. 设置 locale

sudo apt update && sudo apt install -y locales
sudo locale-gen en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

2. 添加 ROS 2 apt 源

# Ubuntu 24.04 (Noble)
sudo apt install -y software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install -y curl
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \
  -o /usr/share/keyrings/ros-archive-keyring.gpg
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" | \
  sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
sudo apt update

3. 安装桌面版（含 RViz + demos）

sudo apt install -y ros-jazzy-desktop
# 仅基础版（无 RViz）：sudo apt install -y ros-jazzy-ros-base

Note

桌面版约 1.2 GB，基础版约 250 MB。树莓派 推荐基础版。

4. 初始化环境

# 每次新 shell 都得 source（或写入 ~/.bashrc）
source /opt/ros/jazzy/setup.bash

# 验证
ros2 --version
# 期望: ros2 cli version: 0.32.x

写入 bashrc 让它自动生效：

echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc
echo "export ROS_DOMAIN_ID=0" >> ~/.bashrc
echo "export ROS_LOCALHOST_ONLY=1" >> ~/.bashrc   # 关闭 mDNS 多机干扰

5. 安装 colcon + 构建工具

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

6. 安装 Zenoh 路由器 (推荐)

sudo apt install -y ros-jazzy-rmw-zenoh-cpp zenohd
# 启动 router
zenohd &

方案 B：Docker 容器

docker run -it \
  --name ros2-jazzy \
  --net=host \
  --ipc=host \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY=$DISPLAY \
  --device /dev/dri:/dev/dri \
  osrf/ros:jazzy-desktop

容器内已经预装好，直接 ros2 run turtlesim turtlesim_node 即可。

验证：跑通 turtlesim (5 min)

打开 3 个终端（都 source 了 setup.bash）：

# 终端 1: 启动小乌龟
ros2 run turtlesim turtlesim_node
# 应该看到一个蓝色窗口，中间一只小乌龟

# 终端 2: 键盘控制
ros2 run turtlesim turtle_teleop_key
# 用方向键控制乌龟移动

# 终端 3: 查看话题
ros2 topic list
# /turtle1/cmd_vel
# /turtle1/color_sensor
# /turtle1/pose
# /parameter_events
# /rosout

ros2 topic echo /turtle1/pose
# 实时显示乌龟位置

第一个工作空间

mkdir -p ~/ros2_ws/src && cd ~/ros2_ws/src
ros2 pkg create --build-type ament_python --node-name my_node my_first_pkg
cd ~/ros2_ws
colcon build --symlink-install
source install/setup.bash
ros2 run my_first_pkg my_node

Tip

--symlink-install 让 install/ 软链到 src/，改 Python 源码后不用重 build。

Zenoh vs DDS

维度	DDS (CycloneDDS / FastDDS)	Zenoh
带宽	高吞吐场景更快	中小吞吐更省
跨网段	❌ 必须组播 / 单播配置	✅ 原生跨网段
资源占用	较重	轻量 5-10 MB
多机调试	配置繁琐	启动 router 即可
稳定性	生产成熟	2024 GA，仍在打磨

新项目推荐 Zenoh。详见 ROS 2 + Zenoh。

常见问题

Caution

ros2 命令找不到 —— 忘记 source。新开终端前执行 source /opt/ros/jazzy/setup.bash。

Caution

“多台机器上看到不同的话题” —— 检查 ROS_DOMAIN_ID 必须一致；默认 0。所有 Jazzy 推荐 ROS_LOCALHOST_ONLY=1 避免 mDNS 冲突。

Caution

“colcon build 卡在 ‘colcon build —symlink-install’” —— 99% 是缺 rosdep 依赖。先 sudo rosdep init && rosdep update，再 build 前 rosdep install --from-paths src --ignore-src -r -y。

Caution

“turtlesim 黑屏 / 闪退” —— 显卡驱动问题。WSL2 用户升级到 WSL 1.3+ 并启用 GPU 支持。

📋 复现条件

类别	必备	可选 / 备注
硬件	x86_64 PC (i5 / Ryzen 5+) 或树莓派 5 8GB · 16GB RAM · 50GB 磁盘	GPU (RViz / Gazebo 加速)
操作系统	Ubuntu 24.04 Noble (官方支持)	Debian 12 / WSL2 / Docker
软件版本	ROS 2 Jazzy Jalisco · colcon 4.0+ · Python 3.12 · GCC 13	rviz2 / rosbag2
网络	联网 (apt + colcon build 下载)	多机通信需千兆网
时间	apt 一键装 10 min · turtlesim 验证 5 min · 第一个 pkg build 30 min	完整开发环境 +1 h
难度	⭐⭐ 入门	apt 装上就能跑
前置知识	Linux 基础 (terminal / apt) · Python	C++ (写 node 用)

Note

macOS 不官方支持。用 Docker 镜像 osrf/ros:jazzy-desktop 跑通最稳。

⛔ 别这么做 (Anti-patterns)

经验证的坑 —— 跳过 = 至少浪费半天，严重的烧板 / 锁机。

❌ 错误做法	💥 后果	⚠️ 风险	范围
不要在 Ubuntu 22.04 上 apt 装 ROS 2 Iron / Rolling	apt 源是滚动版 = 兼容性没保证。ROS 2 永远装 LTS 版 (Humble / Jazzy)。	🟡	ROS 2
不要直接 pip install 全局包做机器人项目	系统 Python 升级 = 依赖破。永远用 venv / uv venv / pixi。	🟡	LeRobot / ACT / OpenVLA 训练
不要把机械臂 / 移动机器人直接接到 12V 铅酸电池	反接 / 短路 = 烧控制板。永远先串 5A 保险丝再接。	🔴	SO-100 / Mobile ALOHA / 自制机器人
不要在没看 dmesg / lsusb 前插 USB 设备并假设会被识别	插上没反应 = 没供电 / 没权限 / 没驱动。先 lsusb -t，再 sudo chmod 666 /dev/ttyUSB0。	🟢	USB 相机 / 串口 / 飞控
不要让 micro-ROS 节点在没看门狗的情况下跑在真机上	死循环 = 整机失控，永远给嵌入式节点加 heartbeat 看门狗。	🔴	micro-ROS / 飞控固件
不要直接拿 GitHub main 分支跑 Mobile ALOHA / LeRobot 训练	main = 正在开发，可能 dataset format 改了 = 跑不通。锁 git checkout v0.4.0 标签。	🟡	Mobile ALOHA / LeRobot
不要在 LeRobot 训练时把 4K 视频存进 dataset	4K 1 小时 ≈ 50GB，30 小时 = 1.5TB IO 瓶颈。先 ffmpeg -vf scale=640:480 降采样。	🟢	LeRobot / ACT 数据采集
不要用 ROS_DOMAIN_ID=0 跑多机协同	0 = 默认域 = 任何人都能收到你的话题。多机实验 = 改 ID (0-232) + Foxy+。	🟢	ROS 2 DDS

🚨 风险总览 (Risk Matrix)

风险等级	含义	例子
🟢 低	改错可回滚 / 几分钟恢复	pip 全局装包、DHCP IP 写死
🟡 中	需要重新刷机 / 重装 / 1-2 小时恢复	装错 ROS 2 版本、没 OTA 升级看版本
🔴 高	不可逆 / 烧板 / 安全风险	电池反接、micro-ROS 没看门狗、刷机中途断电

Note

🔴 高风险 = 必读。执行前确认有 git / flash / 备用设备的回退方案。

下一步

• 🐢 跑通 Mobile ALOHA 改装 (进阶硬件)
• 🧠 在 LeRobot 训练栈 里跑通数据采集
• 🛰️ 升级到 ROS 2 + Zenoh 跨网段