本章目标在 Ubuntu 22.04 上完成 ROS2 Humble 的完整安装与配置建立高效的开发工作流。作为嵌入式工程师你可能已经习惯了 Keil/IAR/VSCode STM32CubeIDE 的开发环境本章将帮助你建立一套同样顺手的 ROS2 开发环境。2.1 Ubuntu 22.04 安装与基础配置2.1.1 为什么必须是 Ubuntu 22.04ROS2 Humble Hawksbill 是官方推荐的 LTS长期支持版本其支持周期如下表格发行版发布日期支持终止支持的 Ubuntu 版本Humble Hawksbill2022.052027.05Ubuntu 22.04 (Jammy)Iron Irwini2023.052024.11已终止Ubuntu 22.04Jazzy Jalisco2024.052029.05Ubuntu 24.04 (Noble)选择 Humble 的理由LTS 稳定性作为首个 5 年支持周期的 ROS2 发行版Humble 经过了最充分的社区验证嵌入式生态成熟micro-ROS、Nav2、MoveIt2 等关键包在 Humble 上最稳定Ubuntu 22.04 兼容性与 NVIDIA Jetson、树莓派等嵌入式平台的官方镜像完美匹配企业级采用率工业界目前最广泛部署的 ROS2 版本虽然 Jazzy 支持到 2029 年但截至 2026 年Humble 仍然是嵌入式/机器人领域的事实标准。如果你是初学者跟随本书使用 Humble 是最稳妥的选择。2.1.2 安装方式选择根据你的硬件条件有三种安装路径方式适用场景优点缺点物理机双系统有闲置 PC/工控机性能最佳硬件直通需要独立硬盘分区虚拟机 (VMware/VirtualBox)Windows 主力机不影响现有系统3D 加速受限Gazebo 卡顿WSL2 (Windows Subsystem)Windows 11 用户与 Windows 深度集成网络/串口设备映射较复杂嵌入式工程师建议如果你有闲置的 x86 工控机或旧笔记本i5 及以上8GB 内存强烈建议物理机安装。因为后续章节涉及 Gazebo 仿真、RViz 可视化、以及 micro-ROS Agent 与 STM32 的串口通信物理机的稳定性和硬件兼容性远胜虚拟化方案。2.1.3 物理机安装步骤简要下载 Ubuntu 22.04.5 LTS ISO# 官方镜像国内访问较慢 https://releases.ubuntu.com/22.04/ubuntu-22.04.5-desktop-amd64.iso # 推荐国内镜像源清华/阿里云 https://mirrors.tuna.tsinghua.edu.cn/ubuntu-releases/22.04/制作启动盘Windows使用 Rufus 或 Ventoy 写入 ISO 到 U 盘Linux/macOSsudo dd ifubuntu-22.04.5-desktop-amd64.iso of/dev/sdX bs4M statusprogressBIOS 设置关闭 Secure BootROS2 部分驱动需要选择 UEFI 模式启动若安装后无法引导检查 SATA 模式是否为 AHCI非 RAID分区建议256GB SSD 为例/boot/efi 512MB EFI 系统分区 /boot 1GB 内核与引导文件 / 80GB 根目录系统软件 /home 150GB 用户数据代码、rosbag、仿真模型 swap 8GB 交换分区内存≥16GB 可省略2.1.4 安装后的基础配置1. 更换国内软件源加速后续下载# 备份原配置 sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak # 编辑源列表选择你所在地区最快的镜像 sudo nano /etc/apt/sources.list将内容替换为清华源Jammy 即 22.04 代号deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-security main restricted universe multiversebashsudo apt update sudo apt upgrade -y2. 安装基础工具链# 构建工具 sudo apt install -y build-essential cmake git wget curl # Python 开发环境ROS2 大量使用 Python sudo apt install -y python3-pip python3-venv python3-colcon-common-extensions # 常用工具 sudo apt install -y htop vim net-tools can-utils # 串口工具后续连接 STM32 需要 sudo apt install -y minicom picocom3. 配置 Git代码版本管理git config --global user.name Your Name git config --global user.email your.emailexample.com git config --global init.defaultBranch main4. 中文输入法可选sudo apt install -y fcitx5 fcitx5-chinese-addons fcitx5-frontend-gtk4 # 注销后重新登录在设置→键盘中添加中文输入法2.2 ROS2 Humble 安装2.2.1 设置 LocaleROS2 需要 UTF-8 编码支持locale # 检查当前设置 # 若未设置执行以下命令 sudo apt update sudo apt install -y locales sudo locale-gen en_US en_US.UTF-8 sudo update-locale LC_ALLen_US.UTF-8 LANGen_US.UTF-8 export LANGen_US.UTF-8 locale # 再次验证注意虽然可以设置为中文 locale但 ROS2 社区大量文档和日志使用英文建议保持en_US.UTF-8以避免潜在编码问题。2.2.2 添加 ROS2 软件源# 安装依赖 sudo apt install -y software-properties-common sudo add-apt-repository universe # 添加 ROS2 GPG key sudo apt update sudo apt install -y curl gnupg lsb-release sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg # 添加仓库到 sources.list echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] https://packages.ros.org/ros2/ubuntu jammy main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null # 更新索引 sudo apt update国内用户加速若 GitHub 访问缓慢可使用清华镜像源替代官方源bashecho deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu jammy main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null2.2.3 安装 ROS2 HumbleROS2 提供两种安装选项安装类型命令大小适用场景Desktop 完整版推荐ros-humble-desktop~2.5GB包含 RViz、Gazebo、仿真工具Base 基础版ros-humble-ros-base~1GB仅核心通信库无 GUI 工具对于本文学习强烈推荐 Desktop 完整版sudo apt update sudo apt install -y ros-humble-desktop安装过程约 15-30 分钟取决于网络速度。安装完成后系统已包含rclcpp/rclpyC/Python 客户端库RMW 实现默认 Fast DDSros2cli命令行工具集RViz23D 可视化工具Gazebo物理仿真器TurtleSim2D 教学仿真环境2.2.4 安装开发工具与依赖# 构建工具colcon 是 ROS2 的构建系统对应 ROS1 的 catkin sudo apt install -y python3-colcon-common-extensions python3-rosdep # 初始化 rosdep依赖解析工具类似 apt 但针对 ROS 包 sudo rosdep init rosdep updaterosdep 常见问题若sudo rosdep init报错 already initialized说明系统已有初始化记录可跳过。若rosdep update超时多试几次或检查网络代理设置。2.2.5 安装额外工具包建议# 常用 CLI 工具增强 sudo apt install -y ros-humble-rqt* ros-humble-plotjuggler-ros # 导航与仿真相关后续章节需要 sudo apt install -y ros-humble-navigation2 ros-humble-nav2-bringup sudo apt install -y ros-humble-turtlebot3* # 微控制器通信micro-ROS 相关 sudo apt install -y ros-humble-ament* ros-humble-rmw*2.3 环境变量配置与验证2.3.1 配置环境变量ROS2 需要通过source命令加载环境变量。每次打开新终端时都需要执行source /opt/ros/humble/setup.bash为避免每次手动输入将其加入 shell 配置文件# 检查当前使用的 shell echo $SHELL # 通常是 /bin/bash # 追加到 ~/.bashrc echo source /opt/ros/humble/setup.bash ~/.bashrc # 立即生效或重新打开终端 source ~/.bashrc嵌入式工程师提示这与你在 STM32 开发中设置PATH包含交叉编译器链如arm-none-eabi-gcc是同一概念。setup.bash本质上就是设置了一系列环境变量ROS_DISTRO、AMENT_PREFIX_PATH、PYTHONPATH等让系统能找到 ROS2 的命令和库。2.3.2 验证安装1. 基础命令验证# 检查 ROS2 版本 ros2 --version # 预期输出ros2 命令的版本信息如 0.18.3 # 查看已安装的 ROS2 发行版 ros2 distro list # 应显示 humble 等可用发行版 # 检查环境变量 printenv | grep -i ROS # 应显示 ROS_VERSION2, ROS_DISTROhumble 等2. 运行经典示例Talker Listener打开两个终端分别执行# 终端 1发布者Talker source /opt/ros/humble/setup.bash # 若已加入 .bashrc 可省略 ros2 run demo_nodes_cpp talker# 终端 2订阅者Listener ros2 run demo_nodes_cpp listener如果看到终端 1 持续输出Publishing: Hello World: 1终端 2 同步输出I heard: [Hello World: 1]说明 ROS2 通信核心工作正常。原理速览这里运行的是 ROS2 的示例包demo_nodes_cpp中的两个节点。talker节点在名为/chatter的 Topic 上发布字符串消息listener节点订阅该 Topic 并打印接收到的内容。Topic 是 ROS2 中最基础的通信机制后续章节会详细展开。3. 可视化验证TurtleSim# 终端 1启动仿真器 ros2 run turtlesim turtlesim_node # 终端 2发送控制指令 ros2 run turtlesim turtle_teleop_key # 按键盘方向键控制小海龟移动如果弹出窗口显示小海龟并能用键盘控制说明图形界面和事件循环也工作正常。4. 节点与 Topic 查看在第三个终端中# 查看当前运行的节点 ros2 node list # 输出/turtlesim, /teleop_turtle # 查看活跃的 Topic ros2 topic list # 输出/turtle1/cmd_vel, /turtle1/pose, /turtle1/color_sensor # 查看 Topic 数据类型 ros2 topic info /turtle1/cmd_vel # 输出Type: geometry_msgs/msg/Twist # 实时打印 Topic 数据 ros2 topic echo /turtle1/pose2.3.3 常见问题排查问题现象可能原因解决方案ros2: command not found环境变量未加载执行source /opt/ros/humble/setup.bashPackage demo_nodes_cpp not found安装不完整sudo apt install ros-humble-demo-nodes-cpp多机通信失败DDS 发现配置问题检查防火墙设置ROS_LOCALHOST_ONLY1Gazebo 启动黑屏/崩溃显卡驱动问题安装 proprietary 驱动或设置LIBGL_ALWAYS_SOFTWARE1中文路径导致编译失败ROS2 不支持非 ASCII 路径确保工作空间路径全为英文2.4 VSCode ROS2 插件配置作为嵌入式工程师你可能已经熟悉 VSCode 的 STM32 开发环境。本节将配置一套同样高效的 ROS2 C/Python 开发环境。2.4.1 安装 VSCode# 方式 1通过 snap 安装推荐自动更新 sudo snap install code --classic # 方式 2手动下载 .deb 包 wget https://code.visualstudio.com/sha/download?buildstableoslinux-deb-x64 -O vscode.deb sudo dpkg -i vscode.deb sudo apt install -f # 修复依赖2.4.2 必装插件清单打开 VSCode按CtrlShiftX进入扩展市场安装以下插件插件名称发布者功能说明ROSMicrosoftROS 语法高亮、launch 文件支持、消息类型跳转C/CMicrosoftC IntelliSense、调试、代码格式化PythonMicrosoftPython 语法高亮、Linting、调试CMake ToolsMicrosoftCMake 项目构建支持ROS2 使用 ament_cmakeament_task_providernonanonnoament/colcon 构建任务集成XML ToolsRed Hatlaunch/param 文件格式化与验证YAMLRed HatYAML 配置文件支持Bracket Pair ColorizerCoenraads括号匹配阅读复杂 launch 文件时非常有用搜索技巧在扩展市场搜索ROS2或ament筛选下载量最高的插件。避免安装过多功能重复的插件。2.4.3 工作区配置ROS2 使用colcon作为构建系统对应 ROS1 的 catkin_make/catkin build。在 VSCode 中配置构建任务1. 创建工作空间mkdir -p ~/ros2_ws/src cd ~/ros2_ws2. 配置 VSCode 工作区设置在工作空间根目录创建.vscode/settings.json{ ros.distro: humble, python.autoComplete.extraPaths: [ /opt/ros/humble/lib/python3.10/site-packages ], python.analysis.extraPaths: [ /opt/ros/humble/lib/python3.10/site-packages ], C_Cpp.default.intelliSenseMode: gcc-x64, C_Cpp.default.compilerPath: /usr/bin/gcc, C_Cpp.default.cppStandard: c17, C_Cpp.default.includePath: [ /opt/ros/humble/include/**, ${workspaceFolder}/install/**/include ], cmake.configureOnOpen: false, files.associations: { *.launch: xml, *.yaml: yaml } }3. 配置构建任务创建.vscode/tasks.json{ version: 2.0.0, tasks: [ { label: colcon build, type: shell, command: colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPERelWithDebInfo, group: { kind: build, isDefault: true }, problemMatcher: [], detail: Build the workspace with colcon }, { label: colcon test, type: shell, command: colcon test colcon test-result --verbose, group: test, problemMatcher: [] } ] }参数说明--symlink-install以符号链接方式安装 Python 脚本和 launch 文件修改后无需重新编译即可生效开发阶段强烈建议-DCMAKE_BUILD_TYPERelWithDebInfo带调试信息的发布模式平衡性能与调试能力4. 配置调试C 节点创建.vscode/launch.json{ version: 0.2.0, configurations: [ { name: Debug ROS2 Node, type: cppdbg, request: launch, program: ${workspaceFolder}/install/package_name/lib/package_name/node_name, args: [], stopAtEntry: false, cwd: ${workspaceFolder}, environment: [ {name: ROS_DISTRO, value: humble}, {name: ROS_LOCALHOST_ONLY, value: 1} ], externalConsole: false, MIMode: gdb, setupCommands: [ { description: Enable pretty-printing for gdb, text: -enable-pretty-printing, ignoreFailures: true } ] } ] }嵌入式工程师对比这与你在 VSCode 中配置arm-none-eabi-gdb调试 STM32 类似只是这里使用本地gdb而非远程 GDB Server。2.4.4 代码风格配置ROS2 有官方的代码风格规范基于 Google C Style 的变体。安装格式化工具sudo apt install -y clang-format pip3 install autopep8 # Python 格式化在 VSCode 中启用保存时自动格式化// 追加到 .vscode/settings.json { editor.formatOnSave: true, C_Cpp.clang_format_style: file, C_Cpp.clang_format_fallbackStyle: Google, python.formatting.provider: autopep8 }2.5 可选Docker 方式运行 ROS2如果你希望保持主机系统干净或需要在同一台机器上快速切换 ROS2 版本Docker 是理想选择。2.5.1 安装 Docker# 卸载旧版本 sudo apt remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt update sudo apt install -y ca-certificates curl gnupg lsb-release # 添加 Docker 官方 GPG key sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 设置仓库 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装 Docker Engine sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 验证安装 sudo docker run hello-world # 免 sudo 使用 Docker需重新登录生效 sudo usermod -aG docker $USER2.5.2 拉取 ROS2 Humble 镜像# 官方镜像包含 Desktop 环境 docker pull osrf/ros:humble-desktop-full # 或使用 ROS 官方基础镜像更轻量 docker pull ros:humble-ros-base2.5.3 运行容器带 GUI 支持由于 ROS2 大量使用 RViz、Gazebo 等 GUI 工具需要配置 X11 转发# 允许本地 X Server 接收连接 xhost local:docker # 运行容器 docker run -it \ --name ros2_humble \ --privileged \ --network host \ -e DISPLAY$DISPLAY \ -e QT_X11_NO_MITSHM1 \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v $HOME/ros2_ws:/root/ros2_ws \ -v /dev:/dev \ osrf/ros:humble-desktop-full \ bash参数说明--privileged授予容器访问主机设备的权限串口、USB 等后续连接 STM32 需要--network host使用主机网络栈DDS 发现需要-v /dev:/dev映射设备文件访问/dev/ttyUSB0等串口-v $HOME/ros2_ws:/root/ros2_ws挂载工作空间到容器内2.5.4 创建便捷的启动脚本在主机~/.bashrc中添加别名alias ros2-dockerxhost local:docker docker start ros2_humble docker exec -it ros2_humble bash alias ros2-docker-freshxhost local:docker docker run -it --rm --privileged --network host -e DISPLAY$DISPLAY -e QT_X11_NO_MITSHM1 -v /tmp/.X11-unix:/tmp/.X11-unix -v $HOME/ros2_ws:/root/ros2_ws -v /dev:/dev osrf/ros:humble-desktop-full bash2.5.5 Docker vs 物理机的选择建议维度物理机安装Docker 方案性能100% 原生性能~95-98%GUI 略有开销串口/硬件直接访问需--privileged映射DDS 多机通信零配置需--network host环境隔离单一环境可多版本并存系统污染软件包安装到系统完全隔离学习曲线低需了解 Docker 基础建议如果你是 ROS2 初学者先用物理机安装走完本书所有示例。待熟悉后若需要维护多个项目或版本再迁移到 Docker。2.6 环境验证清单完成本章后请确认以下检查项全部通过[ ] Ubuntu 22.04 成功启动locale 设置为en_US.UTF-8[ ]ros2 --version返回版本号[ ]ros2 run demo_nodes_cpp talkerlistener跨终端通信成功[ ]ros2 run turtlesim turtlesim_node图形界面正常显示[ ] VSCode 能打开~/ros2_wsC 代码有 IntelliSense 提示[ ]CtrlShiftB能触发 colcon build虽然此时工作空间为空[ ] 可选Docker 容器内能运行ros2 topic list本章小结Ubuntu 22.04 ROS2 Humble 是本书的标准开发平台Humble 作为首个 5 年 LTS 版本是 2026 年最稳定、生态最成熟的选择。环境变量配置是 ROS2 开发的基础理解setup.bash的作用等同于理解交叉编译工具链的PATH设置。VSCode colcon 构成了 ROS2 的高效开发工作流--symlink-install是开发阶段必须掌握的编译选项。Docker 提供了环境隔离的备选方案但在硬件交互串口、DDS 多机时需要额外配置。在下一章我们将创建你的第一个 ROS2 工作空间和功能包正式踏上 ROS2 开发之旅。