ROS2_learn/doc/01-quickstart.md

01 · 5 分钟上手 Quickstart(完整图文版)

目标:从"零"到"看到第一个 ROS2 消息流",每步带预期输出 + 排错,5 分钟内完成。

---

目录

• Step 0: 准备清单
• Step 1: 安装 Docker
• Step 2: 拉取并构建镜像
• Step 3: 启动容器
• Step 4: 在容器内编译
• Step 5: 跑你的第一个 demo
• Step 6: 本机 venv 开发工作流
• Step 7: 验证清单
• Step 8: 常见问题 FAQ

---

Step 0: 准备清单

项	需要
操作系统	Windows 10/11 · macOS 12+ · Linux(Ubuntu 20.04+)
Docker	Docker Desktop(Win/macOS)或 Docker Engine(Linux)
磁盘空间	8 GB 可用(Docker 镜像 + 构建缓存)
网络	首次构建需要下载 ~3 GB 镜像
时间	首次构建 5-10 分钟;后续秒级

💡 Windows 用户:在 BIOS 里开启虚拟化(Intel VT-x / AMD-V),否则 Docker 起不来。

---

Step 1: 安装 Docker

1.1 Windows

1. 下载 Docker Desktop for Windows
2. 双击安装,需要 WSL 2 后端(安装时它会提示)
3. 重启电脑
4. 启动 Docker Desktop,等到右下角鲸鱼图标不再转动

1.2 macOS

brew install --cask docker
# 启动 Docker Desktop

1.3 Linux

# Ubuntu
sudo apt install docker.io docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
# 重新登录后生效

1.4 验证 Docker 装好

docker --version
# Docker version 29.4.3, build ...

docker compose version
# Docker Compose version v5.1.3

若报 Cannot connect to Docker daemon: 启动 Docker Desktop(Win/macOS)或 sudo systemctl start docker(Linux)。

---

Step 2: 拉取并构建镜像

2.1 进入项目目录

# Windows PowerShell
cd D:\xs\ros2

# Linux / macOS
cd /path/to/ros2

2.2 构建镜像(首次 5-10 分钟)

docker compose -p ros2 -f docker/docker-compose.yml build

这一步做了什么:

1. 拉 osrf/ros:humble-desktop 基础镜像(约 2 GB)
2. 装 colcon-common-extensions、colcon-argcomplete 等开发工具
3. 打 tag 为 ros2-humble-dev:latest

预期输出(末尾):

#10 exporting layers 1.5s done
#10 exporting manifest sha256:xxxxx 0.0s done
#10 exporting config sha256:xxxxx 0.0s done
#10 naming to docker.io/library/ros2-humble-dev:latest done

 Image ros2-humble-dev:latest Built

若报 ERROR: pull access denied:

• 检查网络(可能在国内,需要配 Docker 镜像加速器)
• 或: docker pull osrf/ros:humble-desktop 单步测试

2.3 验证镜像

docker images
# REPOSITORY          TAG              IMAGE ID       CREATED          SIZE
# ros2-humble-dev    latest           abc123def456    1 minute ago     3.4GB
# osrf/ros            humble-desktop   789xyz...       3 weeks ago      2.1GB

---

Step 3: 启动容器

docker compose -p ros2 -f docker/docker-compose.yml up -d

参数说明:

• -p ros2:compose project 名,所有容器归在 ros2 项目下(脱离默认 docker)
• up -d:后台启动(-d = detached)
• container_name: ros2_dev:容器名叫这个
• networks: ros2_net:自定义 bridge(脱离 docker_default,IP 段 172.20.0.0/24)

预期:

[+] Running 2/2
 ✔ Container ros2_dev  Created
 ✔ Container ros2_dev  Started

验证容器在跑:

docker ps
# CONTAINER ID   IMAGE                 NAMES      ...
# abc123def456   ros2-humble-dev:latest ros2_dev  Up X seconds

进入开发终端:

docker exec -it ros2_dev bash -lc "source /opt/ros/humble/setup.bash && source /root/ros2_ws/install/setup.bash && exec bash"

❗ 两个 source 都要有:

• source /opt/ros/humble/setup.bash — 加载 ROS2 环境变量(rclpy / colcon / ros2 CLI)
• source /root/ros2_ws/install/setup.bash — 加载本项目 12 个编译产物(只有 build 后才有 install/,第 4 步前先注释掉这一行)

你应该看到类似:

root@docker-desktop:/root/ros2_ws#

💡 小技巧: 用 bash scripts/shell.sh 一键进入(自动检查容器是否在跑 + 启动 + source)。

---

Step 4: 在容器内编译

4.1 准备编译

# 在容器内
source /opt/ros/humble/setup.bash   # 加载 ROS2 环境
cd /root/ros2_ws                     # 进入工作空间

4.2 编译所有包

bash scripts/build.sh

(脚本封装了 source /opt/ros/humble/setup.bash + colcon build --symlink-install --executor sequential 12 个包;手动等价命令见下)

手动等价命令:

source /opt/ros/humble/setup.bash
cd /root/ros2_ws
colcon build --symlink-install --executor sequential \
  --packages-select \
    py_pubsub cpp_pubsub py_srv py_action_demo \
    cpp_robot_tf2 py_vision_demo py_params \
    cpp_custom_interface py_lifecycle_composable \
    cpp_qos_demo py_overlay_dds bringup

❗ --executor sequential 必需。colcon 默认并行构建 12 个包,cpp_custom_interface 的 rosidl export cmake 步骤会偶发失败(已知 CMake bug)。串行构建稳定通过。

预期输出(末尾):

Finished <<< py_pubsub [9.5s]
Finished <<< cpp_pubsub [42s]
Finished <<< py_srv [11s]
Finished <<< py_action_demo [17s]
Finished <<< cpp_robot_tf2 [49s]
Finished <<< py_vision_demo [11s]
Finished <<< py_params [12s]
Finished <<< cpp_custom_interface [38s]
Finished <<< py_lifecycle_composable [8s]
Finished <<< cpp_qos_demo [22s]
Finished <<< py_overlay_dds [9s]
Finished <<< bringup [12s]

Summary: 12 packages finished [3min 30s]

编译产物位置:

/root/ros2_ws/install/  ← source 这个目录才能用 ros2 命令
├── py_pubsub/
├── cpp_pubsub/
├── py_srv/
├── py_action_demo/
├── cpp_robot_tf2/
├── py_vision_demo/
├── py_params/
├── cpp_custom_interface/
├── py_lifecycle_composable/
├── cpp_qos_demo/
├── py_overlay_dds/
└── bringup/

4.3 跑测试(可选)

bash scripts/test.sh

预期:

Summary: 12 packages finished [1min 30s]
  0 packages failed

build/py_pubsub/pytest.xml: 11 tests, 0 errors, 0 failures, 0 skipped
build/cpp_pubsub/test_results/cpp_pubsub/test_pub_sub.gtest.xml: 3 tests, ...
build/py_srv/pytest.xml: 7 tests, ...
...
Summary: 82 tests, 0 errors, 0 failures, 0 skipped

---

Step 5: 跑你的第一个 demo — Topic 跨语言互通

5.1 启动 4 个节点(2 Python + 2 C++)

bash scripts/launch.sh pubsub_launch 30
# 第 2 个参数是运行时长(秒);空着 = 一直跑

预期输出(节点名是 bringup/launch/pubsub_launch.py 里 name= 字段决定的):

[INFO] [launch]: All log files can be found below /root/.ros/log/...
[INFO] [launch]: Default logging verbosity is set to INFO
[INFO] [chatter_publisher-1]: process started with pid [2656]
[INFO] [chatter_publisher_cpp-2]: process started with pid [2658]
[INFO] [chatter_subscriber-3]: process started with pid [2660]
[INFO] [chatter_subscriber_cpp-4]: process started with pid [2662]
[chatter_publisher_cpp-2] [INFO] [...] ChatterPublisher started: rate=2.00 Hz, topic="chatter"
[chatter_publisher-1]    [INFO] [...] ChatterPublisher started: rate=2.00 Hz, topic="chatter"
[chatter_subscriber-3]   [INFO] [...] ChatterSubscriber subscribed: topic="chatter"
[chatter_subscriber_cpp-4] [INFO] [...] ChatterSubscriber subscribed: topic="chatter"
[chatter_subscriber-3]   [INFO] [...] recv #0: "Hello from PY, seq=0"
[chatter_subscriber_cpp-4] [INFO] [...] recv #0: "Hello from C++, seq=0"
[chatter_subscriber-3]   [INFO] [...] recv #1: "Hello from C++, seq=0"   ← 跨语言互通
[chatter_subscriber_cpp-4] [INFO] [...] recv #1: "Hello from PY, seq=1"   ← 跨语言互通
...

按 Ctrl+C 退出。

5.2 在另一个终端验证

新开一个 PowerShell/终端,运行:

docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && source /root/ros2_ws/install/setup.bash && ros2 topic list --no-daemon"

预期输出:

/chatter
/parameter_events
/rosout

看 chatter 频率:

docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && source /root/ros2_ws/install/setup.bash && ros2 topic hz /chatter"

预期:

average rate: 4.000
    min: 0.250s max: 0.260s std dev: 0.00302s window: 10

(4Hz = 2 publisher × 2Hz)

5.3 看通信拓扑(可视化)

新终端:

docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && source /root/ros2_ws/install/setup.bash && ros2 run rqt_graph rqt_graph"

会看到(rqt_graph GUI):

• talker_py → chatter → listener_py
• talker_cpp → chatter → listener_cpp
• 4 节点 2 topic 互通

---

Step 6: 本机 venv 开发工作流

6.1 创建 venv(不污染系统 Python)

# Windows
cd D:\xs\ros2
powershell .\tools\setup_venv.ps1

# Linux / macOS / WSL
cd /path/to/ros2
./tools/setup_venv.sh

预期:

==> Python: Python 3.10.x
==> Creating venv at .venv
==> Upgrading pip + installing requirements-dev.txt
    OK py_pubsub
    OK py_srv
    OK py_action_demo
    OK py_vision_demo
✅ venv ready. Activate with:
    .\.venv\Scripts\Activate.ps1

6.2 激活 venv

# Windows
.\.venv\Scripts\Activate.ps1

# Linux / macOS / WSL
source .venv/bin/activate

预期: 终端前缀出现 (.venv),如:

(.venv) PS D:\xs\ros2>

6.3 在 venv 里能做什么 / 不能做什么

能做	不能做
编辑 Python 源码,IDE 自动补全	import rclpy (rclpy 没 Windows wheels)
跑 ruff / black / mypy	跑 ROS2 节点 / launch 文件
装纯 Python 包(numpy / torch / opencv-python)	跑 ros2 CLI 命令

6.4 配置 VSCode / PyCharm

VSCode:

• Ctrl+Shift+P → "Python: Select Interpreter" → 选 .venv\Scripts\python.exe
• 装扩展:Python, Pylance, ROS(可选)
• pyrightconfig.json 已配好

PyCharm:

• Settings → Project → Python Interpreter → 选 .venv\Scripts\python.exe

---

Step 7: 验证清单

按这个清单逐项打勾,全过才算"5 分钟上手成功":

• docker ps 看到 ros2_dev 容器 Up
• docker exec ros2_dev echo hello 输出 hello
• bash scripts/build.sh 12 packages 全 build 成功
• bash scripts/test.sh 全过(12 packages / 82 tests, 0 failed)
• bash scripts/launch.sh pubsub_launch 30 启动 4 节点
• docker exec ros2_dev bash -c "ros2 topic list" 看到 /chatter
• docker exec ros2_dev bash -c "ros2 topic hz /chatter --no-daemon" 显示 ~4Hz
• docker exec ros2_dev bash -c "ros2 topic info /chatter -v --no-daemon" 看到 Python + C++ pub/sub
• venv 装好且激活,python -c "import sys; print(sys.executable)" 显示 .venv 路径

如果有任何一项 ✗,看 Step 8 FAQ。

---

Step 8: 常见问题 FAQ

Q1: 容器启动失败 Cannot connect to Docker daemon

原因: Docker Desktop 没运行 / WSL2 没启动 解决:

• Win/macOS:启动 Docker Desktop,等右下角图标稳定
• Linux:sudo systemctl start docker

Q1.4: ros2 topic info 显示 Publisher count: 4(应该是 2)

原因:bash scripts/launch.sh pubsub_launch forever 或多次调试后,launch fork 出的 chatter_publisher_* 子进程 reparent 到容器 PID 1,下次启动 launch 又起 2 个,累计 4 个。 解决:

docker exec ros2_dev bash /root/ros2_ws/scripts/clean_ros.sh

Q1.5: docker compose up 报 Pool overlaps with other one on this address space

Network ros2_ros2_net Error Error response from daemon:
invalid pool request: Pool overlaps with other one on this address space
failed to create network ros2_ros2_net

原因:compose project 名 ros2 让网络名前缀成 ros2_ros2_net,但仓库里手动(或上次启动)已经创建了 ros2_net,子网重叠 daemon 拒绝。 解决 1(推荐):绕过 compose,直接走 docker run(参考 Step 3)。 解决 2:

docker rm -f ros2_dev
docker network rm ros2_net
docker compose -p ros2 -f docker/docker-compose.yml up -d

Q2: 构建镜像很慢,卡在 pulling image

原因: 网络慢 / 在国内 解决:

# 加 Docker 镜像加速器
# Docker Desktop → Settings → Docker Engine,加:
{
  "registry-mirrors": ["https://docker.mirrors.ustc.edu.cn"]
}

然后 docker compose build 重试。

Q3: bash scripts/build.sh 报 rcl_xxx not found

原因: 没 source ROS2 解决:

source /opt/ros/humble/setup.bash
bash scripts/build.sh

或者 把这句加进 ~/.bashrc:

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

Q4: 容器里 ros2 命令找不到

原因: 没 source install/setup.bash 解决:

source /root/ros2_ws/install/setup.bash
ros2 --help   # 应该输出帮助

Q5: ros2 topic hz 显示 0 Hz

原因: 没节点 publish 数据 解决: 确认 launch 起来了,看到 [INFO] pub: "Hello from..." 日志

Q6: Windows venv 里 import rclpy 飘红

原因: rclpy 没 Windows wheels 解决: 正常现象,不影响阅读代码。要跑 rclpy 在容器里跑

Q7: 容器里 pip install 装不上 ROS2 包

原因: 你在容器 venv,ROS2 包来自 apt 解决:

# 不在容器 venv 里
exit   # 退出 venv
# 或用 apt
sudo apt install ros-humble-<pkg>

Q8: 容器里中文显示乱码

原因: 容器没装中文字体 解决: 在容器内 export LANG=C.UTF-8 LC_ALL=C.UTF-8

Q9: colcon build 报 CMakeCache 或 export_cpp_custom_interface__rosidl_generator_cExport 错误

原因: 上次 build 残留 CMakeCache,或 cpp_custom_interface 的 rosidl export cmake 并行构建偶发失败 解决:

cd /root/ros2_ws
bash scripts/clean.sh              # 等价于 rm -rf build install log
bash scripts/build.sh              # 脚本已带 --executor sequential

如果还挂,加上 --cmake-clean-cache:

colcon build --symlink-install --executor sequential --cmake-clean-cache \
  --packages-select <12 个包>

Q10: 容器跑一段时间后磁盘满了

原因: build/ install/ log/ 默认在本目录 解决:

# 进容器清理
docker exec ros2_dev bash /root/ros2_ws/scripts/clean.sh
docker exec ros2_dev bash /root/ros2_ws/scripts/build.sh

# 或清理 Docker
docker system prune -a

---

下一步

5 分钟上手成功!现在你可以:

• 阅读 doc/10-concepts.md — 理解 ROS2 核心概念
• 阅读 doc/20-topics.md — Topic 深度
• 阅读 doc/100-embedded-deployment.md — 三机部署实操
• 阅读 doc/99-embodied-ai.md — 具身智能路径

动手尝试: 改一下 py_pubsub 里 talker 的 period_ms,观察 /chatter 频率变化。这是理解 ROS2 参数的最快方式。

加油,ROS2 之旅开始! 🚀

---

---

📖 阅读路径导航

💡 这是仓库 doc/ 下所有文档的推荐阅读顺序。返回 README 总导航

⏱ 本文预计阅读时间: 30 分钟 📍 当前位置: 第 3 / 24 篇

• ⏮ 上一篇: Level 1-4 学习路线
• ⏭ 下一篇: Node / Topic / Service / Action / TF / Time