ROS 2 开发环境：Humble 安装与节点验证

01 · 确认系统与发行版¶

本教程采用以下系统与发行版组合，安装前请确认目标环境一致：

ROS 2 Humble  ←→  Ubuntu 22.04 LTS

02 · 准备一台 Ubuntu 22.04¶

可使用物理机或虚拟机准备 Ubuntu 22.04 环境。运行图形工具前，应核对显示与图形加速配置。

03 · 设置语言环境（locale）¶

配置 UTF-8 语言环境，避免日志显示与工具链编码异常。

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

04 · 添加 ROS 2 软件源¶

安装前添加 ROS 2 软件源。

sudo apt update && sudo apt install curl gnupg lsb-release
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 $(source /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

05 · 安装 ROS 2¶

sudo apt update
sudo apt upgrade
sudo apt install ros-humble-desktop

ros-humble-desktop是带图形工具的完整版，rviz 和一堆示例节点都在里面。本教程使用此软件包进行节点和图形工具验证。

06 · 让环境变量永久生效¶

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

第一条命令作用于当前终端；第二条将配置写入 ~/.bashrc，供后续终端会话加载。

07 · 发布订阅节点验证¶

开两个终端，一个发消息、一个收消息：

# 终端 A：发布者，每秒发一条消息
ros2 run demo_nodes_cpp talker

# 终端 B：订阅者，把收到的消息打印出来
ros2 run demo_nodes_py listener

终端 B 里不断刷出I heard: [Hello World: N]，就说明安装成功了。也可运行 ros2 --help 检查命令是否可用。

装完 ros-humble-desktop 之后：补齐开发工具链¶

desktop 只保证「能跑」，要自己建包还得装官方推荐的开发工具。下面按官方文档的顺序补齐，每一步都给出验证方式。

一、补齐 ros-dev-tools（官方推荐的开发工具元包）¶

官方 Ubuntu 安装页把安装分成三档：desktop（ROS、RViz、demos、tutorials）、ros-base，以及单独一行 "Development tools: Compilers and other tools to build ROS packages"。22.04 + Humble 的准确命令：

sudo apt update
sudo apt install ros-dev-tools

包名就是 ros-dev-tools，没有 ros-humble- 前缀。网上流传的 ros-humble-ros-dev-tools 在官方文档里查不到，如果 apt 报 “Unable to locate package”，先改成上面这个写法。它装的是「造包」而不是「跑包」的工具链——编译器、colcon、rosdep、vcstool、git 一类；只跟着教程跑例程可以缓一缓，一旦要自己建包就必须装。Debian 侧同名（以官方源实际包名为准）；Humble 的 Tier 1 平台只有 Ubuntu 22.04、RHEL 8 与 Windows 10。

来源：https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debs.html

二、环境变量：source 与写进 ~/.bashrc¶

source /opt/ros/humble/setup.bash
printenv | grep -i ROS    # 应看到 ROS_VERSION=2、ROS_DISTRO=humble

要开机自动生效，官方写法是 echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc。但直接 >> 反复执行会重复追加，环境变量层层堆叠，排错时非常难看，建议加判重：

grep -qxF 'source /opt/ros/humble/setup.bash' ~/.bashrc \
  || echo 'source /opt/ros/humble/setup.bash' >> ~/.bashrc
source ~/.bashrc

用 zsh 则换成 setup.zsh 与 ~/.zshrc。

来源：https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html

三、rosdep 初始化（国内最易卡住的一步）¶

官方教程要求装 python3-rosdep，并明确指出：系统里若有同名的旧包 python3-rosdep2，必须先移除，两者不能共存。

sudo apt remove python3-rosdep2     # 只在装过旧包时需要
sudo apt install python3-rosdep
sudo rosdep init
rosdep update

国内常见坑（以下均为经验/社区方案，非官方支持）：

• rosdep init 提示 20-default.list 已存在：说明此前初始化过，跳过 init 直接 rosdep update。
• rosdep update 卡在 raw.githubusercontent.com：先挂代理，export https_proxy=http://127.0.0.1:7890（端口换成自己的），同一终端里再 rosdep update。
• 官方另提供 ROSDISTRO_INDEX_URL 环境变量指向自定义/镜像索引，写法见「Using Custom Rosdistro Version」；镜像是否可用以其站点说明为准。
• rosdepc 等社区工具能绕过网络问题，但替换了索引与脚本，非官方支持，出问题先回退官方用法。

装完在 workspace 里补依赖：

rosdep install --from-paths src --ignore-src -y

来源：https://docs.ros.org/en/humble/Tutorials/Intermediate/Rosdep.html
来源：https://docs.ros.org/en/humble/How-To-Guides/Using-Custom-Rosdistro.html

四、建工作空间并编译¶

source /opt/ros/humble/setup.bash
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws
colcon build --symlink-install
source install/setup.bash

--symlink-install 让 install/ 用符号链接指回 src/，改 Python 脚本、launch、yaml 不必重编（C++ 仍需重编），适合边写边调。install/setup.bash 会把 underlay 一起 source；只想叠加本工作空间时用 install/local_setup.bash。官方提醒：不要在编译过的那台终端里 source overlay，请新开终端。

验证：ls ~/ros2_ws 应出现 build install log src；ros2 pkg list | grep 你的包名 能找到自己的包。

来源：https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace.html

五、验证：talker / listener、topic、doctor¶

两个终端各自 source 后：

ros2 run demo_nodes_cpp talker      # 终端 A
ros2 run demo_nodes_py listener     # 终端 B

看到 Publishing 与 I heard 即说明 C++ 与 Python 两侧都正常。第三个终端：

ros2 topic list          # 应出现 /chatter、/parameter_events、/rosout
ros2 doctor              # 期望 All <n> checks passed
ros2 doctor --report     # 网络 / 平台 / RMW / 话题的完整报告，提问求助时贴这段

ros2 doctor 只报 warning 通常仍可用，出现 UserWarning: ERROR: 才算该模块检查失败。

来源：https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Getting-Started-With-Ros2doctor.html

六、调试工具：desktop 已含哪些¶

官方对 desktop 的描述是「ROS, RViz, demos, tutorials」，即 rviz2、rqt、turtlesim、demo_nodes_* 基本都在，不必重复装。tf2_tools（view_frames）不保证随 desktop 提供，缺了再补：

sudo apt install ros-humble-rqt ros-humble-rqt-common-plugins ros-humble-rqt-graph
sudo apt install ros-humble-rviz2 ros-humble-tf2-tools ros-humble-turtlesim

不建议用 ros-humble-rqt* 这类通配写法（shell 与 apt 的展开行为容易和预期不一致）；用 apt search ros-humble-rqt 看清楚再装更稳。验证：ros2 run turtlesim turtlesim_node 能开窗，配合 ros2 run turtlesim turtle_teleop_key 可控，rviz2 能起界面。

来源：https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debs.html

七、高频报错速查¶

• ros2: command not found：没 source 或 ~/.bashrc 未生效。执行 source /opt/ros/humble/setup.bash，再用 printenv | grep ROS 确认；装了多个发行版时先看 ROS_DISTRO 是否是 humble。
• Package 'xxx' not found：先 ros2 pkg list | grep xxx 判断是「没装」还是「没 source」。没装则 sudo apt install ros-humble-xxx；装了找不到多为环境问题。
• Could not find a package configuration file provided by "xxx"：CMake 找不到 xxxConfig.cmake。装 ros-humble-xxx、确认 package.xml 里有对应 <depend>，再重新 colcon build。
• colcon build 找不到头文件：本质同上一类。先 rosdep install --from-paths src --ignore-src -y 补齐依赖，再检查声明；依赖改动较大时删掉 build/ install/ 重编最省事。
• SetuptoolsDeprecationWarning 可忽略；真报 ModuleNotFoundError: No module named 'distutils'，通常是用了非系统 Python（conda 或 3.12）。官方明确说明 apt 版 ROS 2 不能与 conda 的 Python 混用，检查 PATH 里有无 conda 路径并注释掉；也不要随手 pip install -U setuptools 动系统包。
• source 时报异常：可先 colcon version-check、sudo apt install python3-colcon* --only-upgrade 升级 colcon。

来源：https://docs.ros.org/en/humble/How-To-Guides/Installation-Troubleshooting.html

八、10 分钟自检清单¶

• [ ] printenv | grep -i ROS 输出 ROS_VERSION=2、ROS_DISTRO=humble
• [ ] 新开终端直接 ros2 --help 可用，无需手动 source
• [ ] ros2 pkg list | wc -l 为几十到上百，且 ros2 pkg list | grep demo_nodes_cpp 有结果
• [ ] talker 打印 Publishing，listener 打印 I heard，两个终端互通
• [ ] ros2 topic list 中出现 /chatter
• [ ] ros2 topic echo /chatter 能持续输出消息
• [ ] ros2 doctor 无 UserWarning: ERROR:
• [ ] sudo rosdep init 已完成、rosdep update 不报错
• [ ] ~/ros2_ws 下 colcon build 成功，source install/setup.bash 后可 ros2 run 自己的包
• [ ] ros2 run turtlesim turtlesim_node 开窗，turtle_teleop_key 可控
• [ ] rviz2 能正常启动