教程►机器人/ROS2

ROS 2 菜鸟教程：Ubuntu 24.04 安装 Jazzy + turtlesim 源码编译（2026 实战）

ROS 2 菜鸟教程：Ubuntu 24.04 安装 Jazzy + turtlesim 源码编译（2026 实战）

适合人群：刚装好 Ubuntu 24.04、想学 ROS 2、看到一堆英文术语就头大的纯新手。

目标：装完之后 ros2 命令能用、turtlesim 小乌龟能跑，并且你能拿到源码自己改。

本文所有步骤都在真机（Ubuntu 24.04 LTS + ROS 2 Jazzy）上跑通过，文末的坑全部来自真实踩雷，不是照搬官方文档。

如果你连 Ubuntu 本身都还没配好，先看这篇导航：Ubuntu 24.04 装机必备：AI 编码工具 + 远程 + 网盘 + 输入法（2026 实战）

零、先确认系统版本

1
cat /etc/os-release

看到 VERSION_ID="24.04"、UBUNTU_CODENAME=noble 就对了。

Ubuntu 24.04 对应的 ROS 2 版本是 Jazzy Jalisco，这是官方配套的 LTS 组合，别装错成 Humble 或 Iron。

架构用 uname -m 看，一般是 x86_64。
国内访问官方源 packages.ros.org 很慢，本文统一用清华镜像。

一、更新系统 + 设置 UTF-8 locale

ROS 2 强依赖 UTF-8，没设好会一直报警告。

1
2
3
4
sudo apt update && sudo apt upgrade -y
sudo apt install -y software-properties-common curl gnupg lsb-release
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8

二、添加 ROS 2 软件源（清华镜像）

1
2
3
4
5
6
7
8
9
10
11
12
13
# 启用 universe 仓库
sudo add-apt-repository -y universe

# 下载 ROS 密钥并放进系统钥匙环
sudo curl -sSL https://mirrors.tuna.tsinghua.edu.cn/rosdistro/ros.key \
     -o /usr/share/keyrings/ros-archive-keyring.gpg

# 写源列表（注意域名是 mirrors.tuna.tsinghua.edu.cn）
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" \
| sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

sudo apt update

预期结果：apt update 末尾出现 mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu 的命中行，无报错。

三、安装 ROS 2 桌面版

1
sudo apt install -y ros-jazzy-desktop ros-dev-tools
  • ros-jazzy-desktop：完整桌面版，含 RViz、Gazebo、turtlesim，学习首选。体积大，下载约 1~2GB，耐心等。
  • ros-dev-tools：含 colcon（编译工具）和 rosdep，开发必备。

装完确认文件就位：

1
ls /opt/ros/jazzy/bin/ros2

四、让终端自动加载 ROS 环境（最大的坑）

ROS 的命令不在系统 PATH 里，必须先 source /opt/ros/jazzy/setup.bash。写进 ~/.bashrc 让新终端自动加载：

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

⚠️ 坑 1：用 sudo 跑脚本，环境变量会写进 root 的家目录

如果你把上面的命令写进脚本、用 sudo bash 脚本 执行，脚本里的 ~ 会变成 **root 的家目录 /root**，结果写进了 /root/.bashrc，你自己的终端根本读不到，于是出现：

1
ros2：未找到命令

排查方法（注意别加 sudo，加 sudo 查的是 root 的）：

1
grep "ros/jazzy/setup.bash" ~/.bashrc

没有就手动补一行（不要加 sudo）。想更稳，可再写一份到 ~/.profile 作为登录 shell 兜底。

五、验证安装

1
ros2 pkg list | grep turtlesim

能列出 turtlesim、rviz2 即成功。再看发行版：

1
echo $ROS_DISTRO    # 应输出 jazzy

注：某些构建不支持 ros2 --version / ros2 -V，会报 unrecognized arguments，这不是装坏了。

冒烟测试（开两个终端）：

1
2
3
4
# 终端 1
ros2 run demo_nodes_cpp talker
# 终端 2
ros2 run demo_nodes_cpp listener

订阅者持续打印 Hello World 说明通信正常。

六、拉取 turtlesim 源码（方便读和改）

系统装的是编译好的文件，看不到源码。源码在 GitHub 的 ros/ros_tutorials 仓库。

⚠️ 坑 2：没有 ros2 分支了，要用 jazzy 分支

网上老教程教你 git clone -b ros2 ...，现在会报：

1
fatal: 远程分支 ros2 在上游 origin 未发现

因为现在按发行版命名分支，Jazzy 对应 **jazzy**。

⚠️ 坑 3：直连 GitHub 常被 TLS 拦截

国内直连会报 GnuTLS recv error (-110): The TLS connection was non-properly terminated.，用镜像即可：

1
2
3
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src
git clone -b jazzy --depth 1 https://ghproxy.net/https://github.com/ros/ros_tutorials.git

预期结果：

1
2
ls ros_tutorials/turtlesim/src/
# turtle.cpp  turtle_frame.cpp  turtlesim  turtlesim.cpp
  • turtlesim.cpp：节点主逻辑（turtlesim_node 入口）
  • turtle_frame.cpp：小乌龟在界面上的绘制
  • turtle.cpp：单只乌龟的行为

⚠️ 坑 4：mkdir 加 sudo 后目录跑到 /root 去了

同样是 ~ 展开问题：sudo mkdir -p ~/ros2_ws/src 会建到 /root/ros2_ws，你在自己家目录里当然看不到。

排查时也要注意：ls /root/ros2_ws 不加 sudo 会因权限不足而静默失败，看起来像”目录不存在”，其实它在。要查就加 sudo：

1
sudo ls -la /root

确认无用的话可清理：sudo rm -rf /root/ros2_ws /root/.ros。

七、从源码编译 turtlesim

编译需要 Qt 开发包（画小乌龟用）：

1
sudo apt install -y libqt5svg5-dev    # qtbase5-dev 已随桌面版装好

编译（只编这一个包）：

1
2
3
cd ~/ros2_ws
source /opt/ros/jazzy/setup.bash
colcon build --packages-select turtlesim

预期结果：结尾出现 Summary: 1 package finished [...]，耗时约 40 秒。

若看到 “overriding turtlesim in /opt/ros/jazzy” 的警告——正常，表示你工作空间编出的版本会覆盖系统版本，方便改代码。

⚠️ 坑 5：缺 libqt5svg5-dev 会编译失败

桌面版只带运行时，从源码编译需要 -dev 开发包，缺了会在 CMake 阶段报找不到 Qt5Svg。

八、运行你自己编的版本

顺序不能反：先 source 系统，再 source 工作空间（overlay 要在上层）。

1
2
3
source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 run turtlesim turtlesim_node

另开一个终端用键盘控制小乌龟（点中该终端，用方向键）：

1
2
3
source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 run turtlesim turtle_teleop_key

九、改代码练手（固定套路）

  1. 编辑 ~/ros2_ws/src/ros_tutorials/turtlesim/src/turtlesim.cpp
  2. 重新编译：
    1
    2
    3
    cd ~/ros2_ws
    source /opt/ros/jazzy/setup.bash
    colcon build --packages-select turtlesim
  3. 重新 source 工作空间并运行，看效果。

常见坑速查表

现象 原因 解决
ros2：未找到命令 环境变量写进了 /root/.bashrc，或没 source 确认 ~/.bashrc 里有 source 行并 source ~/.bashrc
ros2 --version 报 unrecognized 该构建不支持此参数 改用 echo $ROS_DISTRO
clone 报「远程分支 ros2 未发现」 分支已按发行版命名 用 -b jazzy
clone 报 GnuTLS recv error 直连 GitHub 被拦 用 ghproxy.net 镜像
colcon build 找不到 Qt5Svg 缺开发包 sudo apt install -y libqt5svg5-dev
家目录看不到 ros2_ws sudo 建到 /root 了 用普通用户 mkdir -p ~/ros2_ws/src
编译警告 overriding turtlesim 覆盖系统包 正常，忽略即可

FAQ

Q：Ubuntu 24.04 该装哪个 ROS 2 版本？
A：Jazzy Jalisco。它是与 Ubuntu 24.04 官方配套的 LTS 版本，支持周期到 2029 年。

Q：一定要装 desktop 完整版吗？基础版够不够？
A：学习建议 desktop。它自带 RViz、Gazebo、turtlesim 等示例，省去后续反复补装的麻烦，代价只是多几个 GB 磁盘。

Q：为什么我改了源码重新编译，运行的还是旧版本？
A：没重新 source 工作空间。改完要 source ~/ros2_ws/install/setup.bash，且顺序必须在系统 setup.bash 之后。

Q：可以用 Node.js 写 ROS 2 节点吗？需要什么版本？
A：可以，用官方库 rclnodejs，Jazzy 分支要求 Node.js ≥ 16.13.0，推荐 18 或 20 LTS。

Q：turtlesim 的源码到底在哪？
A：系统安装的是编译产物，在 /opt/ros/jazzy/share/turtlesim/；可编辑的源码需要自己 clone，见第六节。

相关阅读

写在最后

这套流程的共性是：每个坑都来自真实踩雷。尤其是「sudo 脚本把配置写进 root 家目录」这个坑，会同时导致 ros2 命令找不到和工作空间消失两个看似不相关的问题——理解了 ~ 在 sudo 下会变成 /root，这两个现象就一并解释了。

如果这篇帮你省下了排查时间，下一步可以试试：用 colcon 建自己的第一个功能包，或者把 turtlesim.cpp 改一改（比如换背景色、让小乌龟初始位置随机），改完立刻能看到效果，是最快建立手感的方式。