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

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

---

## 目录

- [Step 0: 准备清单](#step-0-准备清单)
- [Step 1: 安装 Docker](#step-1-安装-docker)
- [Step 2: 拉取并构建镜像](#step-2-拉取并构建镜像)
- [Step 3: 启动容器](#step-3-启动容器)
- [Step 4: 在容器内编译](#step-4-在容器内编译)
- [Step 5: 跑你的第一个 demo](#step-5-跑你的第一个-demo)
- [Step 6: 本机 venv 开发工作流](#step-6-本机-venv-开发工作流)
- [Step 7: 验证清单](#step-7-验证清单)
- [Step 8: 常见问题 FAQ](#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](https://www.docker.com/products/docker-desktop/)
2. 双击安装,需要 WSL 2 后端(安装时它会提示)
3. 重启电脑
4. 启动 Docker Desktop,**等到右下角鲸鱼图标不再转动**

### 1.2 macOS
```bash
brew install --cask docker
# 启动 Docker Desktop
```

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

### 1.4 验证 Docker 装好
```bash
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 进入项目目录
```bash
# Windows PowerShell
cd D:\xs\ros2

# Linux / macOS
cd /path/to/ros2
```
### 2.2 构建镜像(首次 5-10 分钟)

```bash
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 验证镜像
```bash
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: 启动容器

```bash
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
```

**验证容器在跑**:
```bash
docker ps
# CONTAINER ID   IMAGE                 NAMES      ...
# abc123def456   ros2-humble-dev:latest ros2_dev  Up X seconds
```

**进入开发终端**:
```bash
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 准备编译
```bash
# 在容器内
source /opt/ros/humble/setup.bash   # 加载 ROS2 环境
cd /root/ros2_ws                     # 进入工作空间
```
### 4.2 编译所有包

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

**手动等价命令**:
```bash
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
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
bash scripts/launch.sh pubsub_launch 30
# 第 2 个参数是运行时长(秒);空着 = 一直跑
```

**预期输出**:
```
[INFO] [launch]: All log files can be found below /root/.ros/log/2026-08-03-...
[INFO] [launch]: Default logging verbosity is set to INFO
[INFO] [talker-1]: process started with pid [56]
[INFO] [listener-2]: process started with pid [58]
[INFO] [talker-3]: process started with pid [60]
[INFO] [listener-4]: process started with pid [62]
[talker-1] [INFO] [...] talker_py started -> topic=chatter, period=500ms
[listener-2] [INFO] [...] listener_py subscribed <- chatter
[talker-3] [INFO] [...] talker_cpp started -> topic=chatter, period=500ms
[listener-4] [INFO] [...] listener_cpp subscribed <- chatter
[listener-2] [INFO] [...] recv: "Hello from PY, seq=0"
[listener-4] [INFO] [...] recv: "Hello from C++, seq=0"
[listener-4] [INFO] [...] recv: "Hello from PY, seq=0"   ← **跨语言互通!**
[listener-2] [INFO] [...] recv: "Hello from C++, seq=0"   ← **跨语言互通!**
```

按 **Ctrl+C** 退出。

### 5.2 在另一个终端验证

**新开一个 PowerShell/终端**,运行:
```bash
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
/joint_states
/parameter_events
/rosout
/tf
```

**看 chatter 频率**:
```bash
docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && source /root/ros2_ws/install/setup.bash && ros2 topic hz /chatter --no-daemon"
```

**预期**:
```
average rate: 4.000
    min: 0.250s max: 0.260s std dev: 0.00302s window: 10
```

(4Hz = 2 talker × 2Hz)

### 5.3 看通信拓扑(可视化)

**新终端**:
```bash
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)
```powershell
# Windows
cd D:\xs\ros2
powershell .\tools\setup_venv.ps1
```

```bash
# 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
```powershell
# 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 / 78 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)。

---

## Step 8: 常见问题 FAQ

### Q1: 容器启动失败 `Cannot connect to Docker daemon`
**原因**: Docker Desktop 没运行 / WSL2 没启动
**解决**:
- Win/macOS:启动 Docker Desktop,等右下角图标稳定
- Linux:`sudo systemctl start docker`

### Q2: 构建镜像很慢,卡在 `pulling image`
**原因**: 网络慢 / 在国内
**解决**:
```bash
# 加 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
**解决**:
```bash
source /opt/ros/humble/setup.bash
bash scripts/build.sh
```

**或者** 把这句加进 `~/.bashrc`:
```bash
echo 'source /opt/ros/humble/setup.bash' >> ~/.bashrc
```

### Q4: 容器里 `ros2` 命令找不到
**原因**: 没 source `install/setup.bash`
**解决**:
```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
**解决**:
```bash
# 不在容器 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 并行构建偶发失败
**解决**:
```bash
cd /root/ros2_ws
bash scripts/clean.sh              # 等价于 rm -rf build install log
bash scripts/build.sh              # 脚本已带 --executor sequential
```
如果还挂,加上 `--cmake-clean-cache`:
```bash
colcon build --symlink-install --executor sequential --cmake-clean-cache \
  --packages-select <12 个包>
```

### Q10: 容器跑一段时间后磁盘满了
**原因**: `build/` `install/` `log/` 默认在本目录
**解决**:
```bash
# 进容器清理
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`](10-concepts.md) — 理解 ROS2 核心概念
- 阅读 [`doc/20-topics.md`](20-topics.md) — Topic 深度
- 阅读 [`doc/100-embedded-deployment.md`](100-embedded-deployment.md) — 三机部署实操
- 阅读 [`doc/99-embodied-ai.md`](99-embodied-ai.md) — 具身智能路径

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

加油,ROS2 之旅开始! 🚀

---

---

## 📖 阅读路径导航

> 💡 这是仓库 `doc/` 下所有文档的推荐阅读顺序。[返回 README 总导航](../README.md#-23-篇文档怎么读)
>
> ⏱ **本文预计阅读时间**: 30 分钟
> 📍 **当前位置**: 第 3 / 24 篇

- ⏮ **上一篇**: [Level 1-4 学习路线](00-levels.md)
- ⏭ **下一篇**: [Node / Topic / Service / Action / TF / Time](10-concepts.md)