ROS 2 Humble安装指南

2026-01-07

本文档面向在Quectel Pi H1平台或同类Debian 13 (Trixie) 环境中，构建自定义ROS 2 Humble运行时的开发者、系统集成商与现场交付团队，覆盖从源码同步、依赖准备、编译排障到环境变量配置与通信测试的完整路径。通过该指南，你可以：

获取一套针对工业/机器人场景优化的安装流程，快速建立可裁剪的ROS 2 Humble开发环境；
理解在纯净Debian系统上处理依赖冲突、规避Fast DDS/Connext这类商业中间件时的常见问题与解决策略；
构建可复现的工作空间结构，为CI、自动化部署或多设备同步提供统一模板；
基于附带的示例测试验证C++/Python 节点互通，确保环境可直接用于后续应用开发。

准备工作

操作系统：Debian 13 (Trixie)；
网络：稳定的互联网连接，便于下载依赖与源码；
存储与时间：至少10GB可用空间，1-3小时（取决于性能与网络）；
Python：建议Python 3.10/3.11（3.12+可能存在兼容性问题）；
其他建议：提前更新系统sudo apt-get update && sudo apt-get full-upgrade。

安装步骤

安装基础依赖包

    sudo apt-get update && sudo apt-get full-upgrade
    sudo apt-get install -y \
    python3-flake8-blind-except \
    python3-flake8-class-newline \
    python3-flake8-deprecated \
    python3-mypy \
    python3-pip \
    python3-pytest \
    python3-pytest-cov \
    python3-pytest-mock \
    python3-pytest-repeat \
    python3-pytest-rerunfailures \
    python3-pytest-runner \
    python3-pytest-timeout \
    python3-rosdep2 \
    python3-colcon-core \
    vcstool \
    build-essential \
    git

创建ROS 2工作空间

mkdir -p ~/ros2_humble
cd ~/ros2_humble

获取ROS 2 Humble源代码

cd ~/ros2_humble
mkdir -p src
wget https://raw.githubusercontent.com/ros2/ros2/humble/ros2.repos
vcs import src < ros2.repos

安装系统依赖项
```
sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src --rosdistro humble -y -r \
  --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers python3-vcstool \
              ignition-math6 ignition-cmake2 ignition-common3 ignition-transport8"
```
- 跳过的包说明
  - fastcdr, rti-connext-dds-6.0.1: 商业/可选依赖
  - urdfdom_headers, python3-vcstool: 可能已通过其他方式安装
  - ignition-math6, ignition-cmake2, ignition-common3, ignition-transport8: Debian 13中不可用（Gazebo 相关，非核心功能）
- 常见错误（可以忽略）
  - python3-sip-dev失败：GUI工具（rqt）的依赖，不影响核心功能
  - python3-nose失败：Python 3.12+中已废弃，不影响核心功能

编译源码

colcon build --symlink-install

编译时可能会遇到的问题

问题1：Fast DDS相关错误

错误信息：

Starting >>> rmw_connextdds
--- stderr: rmw_fastrtps_shared_cpp
CMake Deprecation Warning at CMakeLists.txt:15 (cmake_minimum_required):
  Compatibility with CMake < 3.10 will be removed from a future version of
  CMake.

  Update the VERSION argument <min> value.  Or, use the <min>...<max> syntax
  to tell CMake that the project requires at least <min> but has been updated
  to work with policies introduced by <max> or earlier.

CMake Error at CMakeLists.txt:47 (find_package):
  Could not find a package configuration file provided by "fastrtps"
  (requested version 2.6.2) with any of the following names:

    fastrtpsConfig.cmake
    fastrtps-config.cmake

  Add the installation prefix of "fastrtps" to CMAKE_PREFIX_PATH or set
  "fastrtps_DIR" to a directory containing one of the above files.  If
  "fastrtps" provides a separate development package or SDK, be sure it has
  been installed.

---
Failed   <<< rmw_fastrtps_shared_cpp [2.60s, exited with code 1]

原因：rmw_fastrtps_shared_cpp这个包依赖Fast DDS（fastrtps）。未安装Fast DDS，所以CMake找不到fastrtpsConfig.cmake，因此报错。即使你打算使用Cyclone DDS，colcon仍会尝试构建Fast DDS相关包，除非显式跳过。

解决方法：使用Cyclone DDS时直接跳过Fast DDS系列包：

  cd ~/ros2_humble
  export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
  colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release \
  --packages-skip \
  rmw_fastrtps_shared_cpp rmw_fastrtps rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp \
  rmw_connextdds rmw_connextdds_common rmw_connextddsmicro \
  rmw_implementation

问题2：rmw_implementation构建失败

错误信息：

Starting >>> rmw_implementation
[-1762327992435806464.000s] ERROR:colcon.colcon_cmake.task.cmake.build:Failed to find the following files:
-/home/root/ros2_humble/install/rmw_fastrtps_shared_cpp/share/rmw_fastrtps_shared_cpp/package.sh
- /home/root/ros2_humble/install/rmw_fastrtps_cpp/share/rmw_fastrtps_cpp/package.sh
-/home/root/ros2_humble/install/rmw_fastrtps_dynamic_cpp/share/rmw_fastrtps_dynamic_cpp/package.sh
Check that the following packages have been built:
- rmw_fastrtps_shared_cpp
- rmw_fastrtps_cpp
- rmw_fastrtps_dynamic_cpp
Failed   <<< rmw_implementation [0.40s, exited with code 1]

原因：构建系统默认会寻找Fast DDS家族的环境钩子（install下 rmw_fastrtps_* 的package.sh）。你未安装Fast DDS，因此找不到这些文件，导致rmw_implementation、rcl等失败。

解决方法：

明确选择Cyclone DDS：export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

隐藏Fast DDS/Connext源包（避免后续扫描）：

for d in \
  src/**/rmw_fastrtps_shared_cpp \
  src/**/rmw_fastrtps_cpp \
  src/**/rmw_fastrtps_dynamic_cpp \
  src/**/rmw_connextdds \
  src/**/rmw_connextdds_common \
  src/**/rmw_connextddsmicro \
; do
  [ -d "$d" ] && touch "$d/COLCON_IGNORE"
done

用占位package.sh临时绕过相关检查（不影响已编译产物，后续可删除）：

for p in rmw_fastrtps_shared_cpp rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp; do
mkdir -p /home/root/ros2_humble/install/$p/share/$p
printf '#!/bin/sh\n# placeholder for %s\n' "$p" > /home/root/ros2_humble/install/$p/share/$p/package.sh
chmod +x /home/root/ros2_humble/install/$p/share/$p/package.sh
done

先构建Cyclone DDS，再构建rmw_implementation、rcl：

colcon build --symlink-install \
--packages-select rmw_cyclonedds_cpp \
--cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

colcon build --symlink-install \
--packages-select rmw_implementation \
--cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

colcon build --symlink-install \
--packages-select rcl \
--cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF -DRMW_IMPLEMENTATION=rmw_cyclonedds_cpp

继续整编

在解决完以上的问题后，继续进行整编：

# 继续整编（跳过Fast DDS & Connext；关闭测试，加速并减少依赖）
colcon build --symlink-install \
--cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
--packages-skip \
rmw_fastrtps_shared_cpp rmw_fastrtps rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp \
rmw_connextdds rmw_connextdds_common rmw_connextddsmicro

环境变量设置

编译完成后，你需要设置环境变量才能使用ROS 2：

export ros2_source=$PWD
echo -e "source ${ros2_source}/ros2_humble/install/setup.bash" >> $HOME/.bashrc
source $HOME/.bashrc

注意：ros2_source是ros2_humble目录所在的位置，即安装步骤中步骤2创建的ROS 2工作空间。

使用测试

示例

打开一个终端，运行C++ talker示例：
```
ros2 run demo_nodes_cpp talker
```
打开另外一个终端，运行Python listener示例：
```
ros2 run demo_nodes_py listener
```

验证

执行完这两条命令后，您应该会看到talker端的消息：

ros2 run demo_nodes_cpp talker
[INFO] [1728966840.691346935] [talker]: Publishing: 'Hello World: 1'
[INFO] [1728966841.691537928] [talker]: Publishing: 'Hello World: 2'
[INFO] [1728966842.691572879] [talker]: Publishing: 'Hello World: 3'
[INFO] [1728966843.691563207] [talker]: Publishing: 'Hello World: 4'
[INFO] [1728966844.691568120] [talker]: Publishing: 'Hello World: 5'

和listener端的消息：

ros2 run demo_nodes_py listener
[INFO] [1728966840.716456921] [listener]: I heard: [Hello World: 1]
[INFO] [1728966841.698002748] [listener]: I heard: [Hello World: 2]
[INFO] [1728966842.697675740] [listener]: I heard: [Hello World: 3]
[INFO] [1728966843.697643318] [listener]: I heard: [Hello World: 4]
[INFO] [1728966844.697551980] [listener]: I heard: [Hello World: 5]

这说明C++和Python API均正常运行。

wx 图形界面开发

容器部署