ROS 2 Humble安装指南

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

本文档说明在 Quectel Pi 开发板（Debian 13 trixie / ARM64）上从源码构建 ROS 2 Humble 的方法。ROS 2 Humble 官方发行版面向 Ubuntu 22.04，Debian 13 下无现成 apt 包，需在板端从源码构建。本文档所有步骤均在内核 6.1.118-rt36（PREEMPT_RT）、Python 3.13.5、3.9 GB 内存的开发板上实测通过。

简介

ROS 2（Robot Operating System 2）是面向机器人开发的分布式通信框架，Humble 为其长期支持（LTS）版本。在开发板上从源码构建 ROS 2 Humble 的特点：

  • 可裁剪：只构建需要的功能包（RMW 使用 Cyclone DDS，跳过 Connext 等商业中间件）；

  • 板端验证：直接基于开发板的 Debian 13 系统构建，产物与硬件环境匹配；

  • 可复现：工作空间结构与构建参数可模板化，便于 CI 与多设备同步。

磁盘空间提示： 完整编译需 10 GB 以上空间。开发板根分区（/）实测 51 GB（可用约 44 GB）充足，工作空间直接部署在 /root/ros2_humble，无需额外分区。

准备工作

系统要求

项目

要求

操作系统

Debian GNU/Linux 13 (trixie)，实测版本 13.6

架构

ARM64（aarch64）

内核

实测 6.1.118-rt36（PREEMPT_RT）

磁盘

根分区 ≥ 10 GB（实测 51 GB）；源码约 654 MB，编译产物约 3 GB

内存

≥ 3 GB（实测 3.9 GB，无 swap，编译需限制并行度，见编译问题 2）

网络

可访问 GitHub（克隆源码）与 Debian 软件源（安装依赖）

编译时间

demo_nodes 依赖链约 40 分钟（8 核限并行 4）

安装步骤

安装基础依赖包

sudo apt-get update
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 cmake \
    python3-numpy python3-numpy-dev \
    libacl1-dev uncrustify

# 注意：Debian 的 python3-colcon-core 仅提供库，无 CLI 入口，需再安装 colcon（见编译问题 1）
sudo apt-get install -y colcon

创建工作空间

mkdir -p /root/ros2_humble/src
cd /root/ros2_humble

获取 ROS 2 Humble 源代码

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

ros2.repos 包含约 100 个仓库（实测 104 个），源码约 654 MB。若 vcs 卡在某仓库（如 Fast-DDS 大仓库），可改用浅克隆脚本逐个拉取。

安装系统依赖项

sudo rosdep init
rosdep update
cd /root/ros2_humble
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（商业/可选）；urdfdom_headers、python3-vcstool（已装）；ignition-*（Debian 13 不可用，Gazebo 相关）。

常见错误（可忽略）： python3-sip-dev 失败（GUI 工具 rqt 依赖）、python3-nose 失败（Python 3.12+ 废弃），均不影响核心功能。

编译源码

编译策略： RMW 使用 Cyclone DDS（不编译 Connext 等商业中间件），只构建到 demo_nodes 的最小依赖链（Fast DDS 库仍会作为依赖自动编译）：

cd /root/ros2_humble
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

# 实测建议：3.9 GB 内存无 swap，限并行度防止编译高峰设备卡死（见编译问题 2）
colcon build --symlink-install \
  --packages-up-to demo_nodes_cpp demo_nodes_py \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
  --parallel-workers 1 \
  --packages-skip \
  rmw_connextdds rmw_connextdds_common rmw_connextddsmicro rti_connext_dds_cmake_module \
  rviz_assimp_vendor tinyxml_vendor libcurl_vendor zstd_vendor sqlite3_vendor \
  yaml_cpp_vendor shared_queues_vendor

实测编译约 130 个包。编译完成后追加构建 ros2cli 命令行工具（含其依赖包，见编译问题 4）：

source /root/ros2_humble/install/setup.bash
colcon build --packages-select geometry_msgs std_srvs rosidl_runtime_py \
  ros2cli ros2node ros2topic ros2msg ros2service ros2action ros2param ros2pkg ros2run \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

编译问题与解决方法（实测）

问题 1：colcon 命令不存在（command not found）

Debian 的 python3-colcon-core 仅提供库无 CLI 入口，需额外安装 colcon 包：

apt-get install -y colcon

问题 2：编译高峰期设备卡死/自动重启

编译 demo_nodes 链时设备多次卡死（无 OOM 记录、温度 56–59°C 正常），疑似高负载引发。缓解：限核 + 降优先级 + 串行编译：

taskset -c 0-3 nice -n 10 colcon build --symlink-install \
  --packages-up-to demo_nodes_cpp demo_nodes_py \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
  --parallel-workers 1 \
  --packages-skip \
  rmw_connextdds rmw_connextdds_common rmw_connextddsmicro rti_connext_dds_cmake_module \
  rviz_assimp_vendor tinyxml_vendor libcurl_vendor zstd_vendor sqlite3_vendor \
  yaml_cpp_vendor shared_queues_vendor

编译中断后 colcon build 支持增量续编：保留 build/ 与 install/ 目录直接重跑命令即可，已完成的包会跳过。

问题 3：rclpy 报 file too short（.so 为 0 字节）

设备重启中断编译导致 _rclpy_pybind11.cpython-313-aarch64-linux-gnu.so 写入不完整（0 字节）。删除 build/rclpy 与 install/rclpy 后重新编译：

rm -rf build/rclpy install/rclpy
colcon build --packages-select rclpy \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

问题 4：ros2 缺 ros2run / ros2topic 依赖包

ros2 run 需要 ros2run（依赖 ros2pkg）；ros2topic/ros2service 还依赖 geometry_msgs、std_srvs、rosidl_runtime_py（不在 demo_nodes 依赖链中）。按上面「编译源码」一节补充构建即可。

环境变量设置

编译完成后，将 ROS 2 环境写入 ~/.bashrc 实现自动加载：

echo 'source /root/ros2_humble/install/setup.bash' >> ~/.bashrc
echo 'export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp' >> ~/.bashrc
source ~/.bashrc

使用测试

打开一个终端，运行 C++ talker：

ros2 run demo_nodes_cpp talker

打开另一个终端，运行 Python listener：

ros2 run demo_nodes_py listener

验证

实测输出：

[INFO] [talker]: Publishing: 'Hello World: 1'
[INFO] [listener]: I heard: [Hello World: 15]

也可用 ros2 命令行验证话题：

ros2 topic list          # 应显示 /chatter /parameter_events /rosout
ros2 topic info /chatter # Type: std_msgs/msg/String, Publisher count: 1
ros2 node list           # 应显示 /listener /talker

C++ 与 Python API 互通正常，ROS 2 Humble 环境可用于后续应用开发。

常见问题

ros2 命令只显示部分子命令（缺 run/topic 等）

实测现象：只执行 colcon build --packages-up-to demo_nodes_cpp demo_nodes_py 后，ros2 run 报 invalid choice: 'run'，因 demo_nodes 依赖链不含 ros2cli 扩展包。需补充构建（见编译源码一节）：

colcon build --packages-select geometry_msgs std_srvs rosidl_runtime_py \
  ros2cli ros2node ros2topic ros2msg ros2service ros2action ros2param ros2pkg ros2run \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

rclpy 报 file too short（.so 为 0 字节）

设备重启中断编译导致 _rclpy_pybind11.cpython-313-aarch64-linux-gnu.so 写入不完整，ros2 --help 直接 ImportError。删除 build/rclpy 与 install/rclpy 后重编（见编译问题 3）。

pip3 install 报 externally-managed-environment（PEP 668）

Debian 13 默认禁止 pip 写入系统 Python 环境。实测 lark、netifaces 已随系统预装，无需安装；确需安装时加参数：

pip3 install --break-system-packages lark netifaces

后台编译进程随 adb shell 退出被终止

实测 nohup ... & 方式启动编译进程，adb 会话结束后进程被 SIGHUP 杀掉，日志未生成。改用 setsid 或 systemd service 托管：

# systemd 方式
cat > /etc/systemd/system/ros2-build.service << 'EOF'
[Unit]
Description=ROS2 build
[Service]
Type=simple
ExecStart=/bin/bash /root/ros2_humble/build.sh
WorkingDirectory=/root/ros2_humble
StandardOutput=append:/root/ros2_humble/build.log
StandardError=append:/root/ros2_humble/build.log
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload && systemctl start ros2-build.service

系统无法启用 swap（Function not implemented）

内核未启用 CONFIG_SWAP 与 zram，swapon /swapfile 报 Function not implemented。3.9 GB 内存无 swap，编译必须限制并行度（见编译问题 2），不可依赖 swap 缓解。