Environment Setup：建立可复现的 Jazzy 环境
在进入第 1 课前，完成 Ubuntu 24.04、ROS 2 Jazzy、开发工具和终端环境的安装与验收。
没有安装：从系统检查开始。已经安装：不要重装，直接做环境审计。
新安装需要 Ubuntu 24.04、可用网络和 sudo 权限。若你已经安装 Jazzy 且能运行官方 demo，跳过 APT 安装命令，但仍要完成版本核对、source 心智模型、四层验收、故障实验和 Challenge。
你交付的不是一句“ROS 装好了”，而是一份可以回答这些问题的环境证据：
- 系统和 ROS 发行版是什么？
- 包从哪里安装到哪里？
- 为什么新终端找不到 ros2？
- CLI、C++、Python 和节点发现是否都正常？
机器人环境不是“所有软件都装最新版”
ROS 2 以发行版组织一整套相互兼容的软件包。每个发行版都有目标操作系统、受支持架构和维护周期。课程使用 Ubuntu 24.04 Noble + ROS 2 Jazzy：这是 Jazzy 的 Tier 1 Linux 平台，amd64 和 arm64 都有官方 Debian 二进制包。仿真部分再与 Gazebo Harmonic 配套。
这三个版本要当成一个经过测试的组合，而不是三个可以随意替换的名字。比如在 Ubuntu 22.04 上直接照抄 Jazzy 的 Ubuntu 24.04 APT 流程，可能遇到包不存在或依赖不匹配；这时正确动作是重新选择受支持组合，而不是从网上拼接随机修复命令。
cat /etc/os-release
uname -m
dpkg --print-architecture
locale为什么现在执行？在添加软件源之前先证明当前机器是否满足课程基线。安装失败时，这四项也是最先需要的证据。
预期现象VERSION_ID="24.04"，代号 noble；架构通常为 x86_64/amd64 或 aarch64/arm64；locale 至少有一项以 UTF-8 结尾。
你应该读懂uname 使用内核架构名称，dpkg 使用包管理器架构名称，二者写法不同但应互相对应。locale 可以是 zh_CN.UTF-8，不要求必须英文，只要求 UTF-8。
Ubuntu 24.04 + amd64/arm64 + UTF-8
进入正式安装或已安装环境审计。
不是 Ubuntu 24.04
本页命令不再保证适用。不要通过伪造 VERSION_CODENAME 强行安装；应选择匹配发行版、容器或虚拟机。
APT 安装链：系统能力 → ROS 软件源 → Jazzy 包
APT 只有在知道“去哪里找包、如何验证签名”以后，才能安装 ROS 2。官方的 ros2-apt-source 包负责安装 ROS 仓库地址和签名配置；随后 apt update 才能把 ROS 包索引加入本机缓存。理解这条链，会让 “Unable to locate package” 不再是黑盒错误。
确保 UTF-8 locale
如果上一节的 locale 已经全部是 UTF-8，可以保留现有中文或英文 locale，直接进入 STEP 2。
sudo apt update && sudo apt install locales
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
locale为什么现在执行？ROS 工具、Python 和构建系统会处理包名、日志与路径；统一使用 UTF-8 可避免字符编码在不同工具间产生歧义。
预期现象最后一次 locale 输出中 LANG 和 LC_ALL 为 en_US.UTF-8，或你明确保留的其他 UTF-8 locale。
你应该读懂locale-gen 生成语言环境，update-locale 写入系统默认，export 只让当前 shell 立即使用新值。它们解决的层次不同。
启用 Universe 并安装 ROS 软件源配置
下面命令来自 ROS 2 当前官方 Debian 安装流程。它不会安装 ROS 本体，只让 APT 学会安全地找到 ROS 软件包。
sudo apt install software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install curl -y
. /etc/os-release
export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F'"' '{print $4}')
curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/$ROS_APT_SOURCE_VERSION/ros2-apt-source_$ROS_APT_SOURCE_VERSION.${UBUNTU_CODENAME:-${VERSION_CODENAME}}_all.deb"
sudo dpkg -i /tmp/ros2-apt-source.deb为什么现在执行？Universe 提供部分依赖；ros2-apt-source 安装 ROS 仓库地址和签名配置，使后续包能被 APT 验证和发现。
预期现象dpkg 最终显示 ros2-apt-source 已解包并设置完成，没有 404、证书或架构错误。
你应该读懂curl 下载的是一个可由 dpkg 检查和管理的仓库配置包，不是把远程 shell 脚本直接交给 root。变量保存最新配置包的发布标签；/etc/os-release 提供 Ubuntu 的 noble 代号，写法与当前官方安装流程一致。
如果下载 URL 返回 404，先执行 echo $ROS_APT_SOURCE_VERSION，再加载 . /etc/os-release 并执行 echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}}。如果结果不是 noble，本课程的安装路径不适用。不要把代号硬改成 noble 来绕过检查。
更新系统并安装 Desktop 与开发工具
Desktop 包包含 ROS 基础能力、RViz、demo 和教程资源，适合本课程；ros-base 更轻，但第一课使用的完整 demo/GUI 资源可能需要额外安装。
sudo apt update
sudo apt upgrade
sudo apt install ros-jazzy-desktop
sudo apt install ros-dev-tools为什么现在执行？先刷新加入 ROS 仓库后的索引并更新 Ubuntu，再安装课程统一的 Jazzy Desktop 和构建、测试所需开发工具。
预期现象APT 解析依赖后完成安装；/opt/ros/jazzy 目录出现，apt 不再报告未满足依赖或找不到 ros-jazzy-desktop。
你应该读懂ros-jazzy-desktop 是一个元包，它把一组具体包作为依赖安装进 /opt/ros/jazzy。ros-dev-tools 是开发工具集合，不等于 ROS 运行时本身。
已经安装过？展开查看如何审计，不要重复安装
apt-cache policy ros-jazzy-desktop
apt-cache policy ros2-apt-source
dpkg -l | grep -E "ros-jazzy-(desktop|ros-base)"
ls -ld /opt/ros/jazzyInstalled 与 Candidate 能说明包版本和来源；dpkg 状态 ii 表示已安装；/opt/ros/jazzy 是二进制安装的 underlay 根目录。
安装写入磁盘，source 改变当前终端
sudo apt install 把文件安装到 /opt/ros/jazzy，这是持久的磁盘状态；source /opt/ros/jazzy/setup.bash 则读取环境脚本，把可执行文件、Python 模块、库和包索引路径加入当前 shell 进程。关闭终端后，这些环境变量不会自动传给下一个新终端。
因此“新终端里 ros2: command not found”通常不代表 ROS 被卸载了。先检查文件是否仍在 /opt/ros/jazzy，再检查当前 shell 是否加载过环境。以后创建自己的工作空间时，还会在 Jazzy 这个基础环境之上继续叠加 overlay；本节只建立第一层 underlay。
which ros2 || echo "ros2 is not on PATH"
source /opt/ros/jazzy/setup.bash
which ros2
printenv ROS_VERSION
printenv ROS_DISTRO
printenv ROS_PYTHON_VERSION为什么现在执行？把“source 有用”变成可观察的环境差异，而不是记忆一条仪式性命令。
预期现象source 后 which 指向 /opt/ros/jazzy/bin/ros2；ROS_VERSION=2；ROS_DISTRO=jazzy；ROS_PYTHON_VERSION=3。
你应该读懂这些变量是当前 shell 的证据。它们告诉工具使用哪套 ROS 环境，但不会检查每个包都健康，因此还需要下一节的分层验收。
source /opt/ros/jazzy/setup.bashsource /opt/ros/jazzy/setup.zsh. /opt/ros/jazzy/setup.sh“命令存在”只是第一层，不是安装完成
一次可靠验收要逐层证明：环境变量正确、包索引可读、C++/Python 运行库正常、ROS Graph 能发现并通信。每层都有不同证据，这样失败时才知道从哪里开始。
Shell 环境
发行版、ros2 路径和当前 shell 一致。
echo $ROS_DISTRO
which ros2包索引
ament index 能找到 demo 包的安装位置。
ros2 pkg prefix demo_nodes_cpp双语言运行
C++ Talker 与 Python Listener 都能启动并交换数据。
ros2 run demo_nodes_cpp talker
ros2 run demo_nodes_py listener系统诊断
汇总网络、中间件、发行版和接口状态。
ros2 doctor --reportsource /opt/ros/jazzy/setup.bash
ros2 pkg prefix demo_nodes_cpp
ros2 pkg prefix demo_nodes_py
ros2 doctor --report为什么现在执行？先证明 C++/Python demo 包进入索引，再让 ros2 doctor 汇总当前环境与中间件信息。
预期现象两个 pkg prefix 都指向 /opt/ros/jazzy；doctor 报告包含 NETWORK CONFIGURATION、PLATFORM INFORMATION、RMW MIDDLEWARE 等区段。
你应该读懂doctor 的 warning 不一定阻断学习，例如未使用某些接口；error 或 missing package 才需要优先处理。判断时记录完整区段，不要只截取最后一行。
ROS distro、平台、RMW、中间件和网络接口是否符合你的机器。
Warning 是风险提示；Error、命令失败或 demo 无法通信才是阻断问题。
保存完整输出、执行命令、终端环境和时间，不用一张模糊截图代替证据。
把“环境坏了”拆成三个完全不同的问题
新终端没有 source
打开全新终端，不加载 Jazzy，直接运行：
ros2 --help若提示 command not found，先确认 /opt/ros/jazzy/setup.bash 存在，再 source。安装文件没有消失，只是当前 shell 的 PATH 不包含它。
两个终端处在不同 Domain
Talker 终端设置 21，Listener 保持默认：
ROS_DOMAIN_ID=21 ros2 run demo_nodes_cpp talker
ros2 run demo_nodes_py listener两个 Node 都能启动，但不会互相发现。分别检查 printenv ROS_DOMAIN_ID，让参与同一系统的终端使用相同 Domain。
APT 找不到 Jazzy 包
出现 Unable to locate package 时，先收集：
. /etc/os-release
echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}}
apt-cache policy ros-jazzy-desktop
apt-cache policy ros2-apt-source优先检查系统是否 noble、ros2-apt-source 是否安装、apt update 是否成功。不要把版本代号硬改成 noble，也不要立刻加入来历不明的软件源。
判断你理解的是环境，还是只会复制命令
source /opt/ros/jazzy/setup.bash 会把 ROS 2 安装到电脑。
新终端里找不到 ros2，第一反应应该重新安装。
Ubuntu 22.04 也可以直接按本页 Jazzy APT 流程安装。
下面三条证据分别证明了什么？
which ros2
# /opt/ros/jazzy/bin/ros2
ros2 pkg prefix demo_nodes_cpp
# /opt/ros/jazzy
printenv ROS_DISTRO
# jazzy第一条已经能证明整个 ROS 2 环境健康吗？
不能。它只证明 shell 能找到 ros2 CLI。包索引、Python/C++ 运行库、DDS 发现和通信仍需分别验证。
pkg prefix 为什么比“目录看起来存在”更有价值？
它证明当前加载的 ament index 能解析这个包，并告诉你实际使用的是哪一个 underlay/overlay 中的版本。
ROS_DISTRO=jazzy 能排除所有混装问题吗？
不能。它说明当前环境声明为 Jazzy，但后续 source 其他工作空间仍可能覆盖包。将来需要结合 pkg prefix、环境路径和包版本继续判断。
从一个全新终端交付环境验收证据
关闭实验终端，重新打开三个全新终端。不要回看完整命令区，独立完成下面的验收，并把输出保存成一份文本记录。
- 01
证明系统是 Ubuntu 24.04，并记录包管理器架构和 UTF-8 locale。
- 02
加载 Jazzy，证明 ros2 CLI 来自 /opt/ros/jazzy，记录 ROS_DISTRO。
- 03
证明 demo_nodes_cpp 和 demo_nodes_py 都能由包索引找到。
- 04
在相同 ROS_DOMAIN_ID 下运行 C++ Talker 与 Python Listener，观察至少 10 条消息。
- 05
运行 ros2 doctor --report，把 Warning 分成“可解释、不阻断”和“必须修复”两组。
需要提示时再展开
按“系统 → shell → 包 → 进程 → 通信 → 诊断”的顺序组织证据。可能用到 /etc/os-release、dpkg --print-architecture、which、printenv、ros2 pkg prefix、ros2 run 和 ros2 doctor。
完成后核对最低验收线
系统为 noble、架构为 amd64 或 arm64、locale 支持 UTF-8；which ros2 指向 /opt/ros/jazzy/bin/ros2；ROS_DISTRO 为 jazzy；两个 demo 包 prefix 均为 /opt/ros/jazzy；Talker/Listener 能持续通信；doctor 没有导致 CLI、包发现或通信失败的阻断问题。不同机器的 warning 可能不同，不要求机械追求“零 warning”。
可靠 ROS 2 环境 = 受支持版本组合 + 可追溯包来源 + 明确 shell 环境 + 分层验收
APT 把 Jazzy 安装到 /opt/ros/jazzy；setup 脚本把这套安装加入当前 shell；ros2 CLI 通过环境和 ament index 找到包；节点在一致的中间件与 Domain 中发现并通信。任何一层出问题，都应该先用对应证据定位，而不是反复重装。
能在全新终端解释并复现 source，确认 Jazzy、CLI、demo 包和跨语言通信正常，并根据 ros2 doctor 区分警告与阻断问题。
只有“talker 能启动”还不算通过；Challenge 的五组证据缺一不可。