# 02 · 本机 venv 工作流(不污染系统 Python 完全指南)

> **目标**:用标准 Python venv 在 Windows / Linux / macOS 上做 ROS2 开发,**完全不污染系统 Python**。

---

## 目录

- [1. 为什么需要 venv](#1-为什么需要-venv)
- [2. 双轨制 — venv vs colcon](#2-双轨制--venv-vs-colcon)
- [3. 创建 venv(Win / Linux)](#3-创建-venvwin--linux)
- [4. venv 里装了什么](#4-venv-里装了什么)
- [5. IDE 配置](#5-ide-配置)
- [6. 在 venv 里能做什么 / 不能做什么](#6-在-venv-里能做什么--不能做什么)
- [7. 在容器里跑 ROS2 测试](#7-在容器里跑-ros2-测试)
- [8. 依赖锁文件](#8-依赖锁文件)
- [9. .venv 加进 .gitignore](#9-venv-加进-gitignore)
- [10. 故障排查](#10-故障排查)
- [11. 在本仓库里跑](#11-在本仓库里跑)

---

## 1. 为什么需要 venv

ROS2 的 Python 客户端库(`rclpy` / `sensor_msgs` / `tf2_ros` / `cv_bridge` 等)**只在 Linux 平台通过 apt 提供**,
Windows 上没有官方 pip wheels。

如果直接 `pip install` 到系统 Python:
- 失败(找不到 wheel)
- 或者和别的项目冲突(版本冲突)
- 或者哪天升级 Python 把 ROS 客户端搞挂了

**venv 的目的**:本机 Python 工具(ruff / black / pytest / mypy 等)放隔离环境,与 ROS2 运行解耦。

---

## 2. 双轨制 — venv vs colcon

| 工作 | 用什么 | 跑在哪 |
|---|---|---|
| 编辑代码、写测试 | **本机 venv + IDE** | Win/macOS/Linux |
| 跑 ROS2 节点 / colcon build / colcon test | **Docker 容器** | Linux |
| pytest (纯逻辑、不需要 ROS2) | 本机 venv | Win/macOS/Linux |
| pytest (需要 rclpy) | **Docker 容器** | Linux |

```
本机: venv (开发)        Docker: colcon (运行)
─────────────────        ────────────────────
ruff / black / mypy       colcon build
pytest (纯逻辑)           colcon test
IDE 跳转                  ros2 run / launch
                         rclpy / sensor_msgs / tf2_ros
```

---

## 3. 创建 venv

### 3.1 Windows

```powershell
cd D:\xs\ros2
powershell .\tools\setup_venv.ps1

# 激活
.\.venv\Scripts\Activate.ps1

# 验证
python -c "import sys; print(sys.executable)"
# 期望: D:\xs\ros2\.venv\Scripts\python.exe (不是 C:\Program Files\Python310\python.exe)
```

### 3.2 Linux / macOS / WSL

```bash
cd /path/to/ros2
./tools/setup_venv.sh

source .venv/bin/activate
python -c "import sys; print(sys.executable)"
# 期望: /path/to/ros2/.venv/bin/python
```

### 3.3 在 Docker 容器内

容器内系统 Python 已经隔离,venv 多此一举。直接用系统 Python 即可。

---

## 4. venv 里装了什么

`tools/setup_venv.{sh,ps1}` 会做:

1. `python -m venv .venv` — 创建虚拟环境
2. `pip install --upgrade pip setuptools wheel`
3. `pip install -r requirements-dev.txt` — 装开发工具:
   - `ruff`(超快 linter,替代 flake8 + isort)
   - `black`(格式化)
   - `mypy`(类型检查)
   - `pytest` + `pytest-cov` + `pytest-timeout`
   - `pre-commit`(git hook,可选)
4. `pip install -e src/py_pubsub src/py_srv src/py_action_demo src/py_vision_demo`
   把本项目 ROS2 Python 包装到 venv(**可编辑模式** — 改源码立即生效,不需要重装)
   `--no-deps` 跳过 ROS 客户端依赖(因为 Windows 装不上)

---

## 5. IDE 配置

### 5.1 VSCode

`pyrightconfig.json` 已配置好,直接:
```json
{
  "extraPaths": [
    "/opt/ros/humble/lib/python3.10/site-packages"   // 容器内
  ]
}
```

设置 VSCode 的 Python 解释器:`Ctrl+Shift+P` → "Python: Select Interpreter" → 选择 `.venv\Scripts\python.exe`

### 5.2 PyCharm

`Settings → Project → Python Interpreter → Add → Existing environment` → 选 `.venv\Scripts\python.exe`

### 5.3 看代码跳转
- 跳转到 `rclpy.Node` 定义:`Ctrl+点击` — pyright 会去 `/opt/ros/humble/lib/python3.10/site-packages` 找
- **容器外**:Windows 上 import rclpy 仍然飘红,但不影响阅读源码
- **容器内(开发容器)**:跳转正常,因为 `/opt/ros/...` 路径存在

---

## 6. 在 venv 里能做什么 / 不能做什么

| 能做 | 不能做 |
|---|---|
| 编辑 Python 源码,IDE 自动补全 | `import rclpy` (rclpy 没 Windows wheels) |
| 跑 ruff / black / mypy | 跑 ROS2 节点 / launch 文件 |
| 装纯 Python 包(numpy / torch / opencv-python) | 跑 ros2 CLI 命令 |
| 在容器内 venv(可访问 rclpy):跑纯 pytest | |

---

## 7. 在容器里跑 ROS2 测试

```bash
docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && cd /root/ros2_ws && colcon test --packages-select py_pubsub"
```

colcon test 会自动跑每个包的 `test/` 目录下的测试。本仓库:
- `py_*` 包 → pytest
- `cpp_*` 包 → ament_cmake_gtest(CTest)
- 期望全部 PASSED。

---

## 8. 依赖锁文件

生产环境建议加 `requirements.lock`(`pip freeze > requirements.lock`),精确锁版本。本仓库的
`requirements*.txt` 只列宽松版本(`>=`):

| 文件 | 用途 |
|---|---|
| `requirements.txt` | 运行时纯 Python 依赖(numpy / pytest) |
| `requirements-dev.txt` | 开发工具(ruff / black / mypy) |

---

## 9. .venv 加进 .gitignore

```gitignore
.venv/
```

已加。提交代码不会带 venv 目录。

---

## 10. 故障排查

### 10.1 `python: command not found`
- Windows:安装 Python 3.10+ 并勾选 "Add to PATH"
- Linux: `sudo apt install python3 python3-venv`

### 10.2 `venv` 模块找不到
```bash
# Debian/Ubuntu
sudo apt install python3-venv

# Fedora/RHEL
sudo dnf install python3-virtualenv
```

### 10.3 venv 里 `import rclpy` 仍然飘红
正常。rclpy 在 Windows 没有 pip wheels,需要靠 apt(在容器内)。开发时不影响阅读,
要跑 ROS2 测试就在容器里跑。

### 10.4 venv 占空间
通常 200-500 MB。删掉重建:`rm -rf .venv && tools/setup_venv.sh`。

### 10.5 激活 venv 后 pip 装不上
确认 `which python` / `which pip` 指向 `.venv/bin/`:
```bash
which python   # /path/.venv/bin/python
which pip      # /path/.venv/bin/pip
```

如果指向系统 Python,venv 没生效。

---

## 11. 在本仓库里跑

### 11.1 创建 venv

```powershell
cd D:\xs\ros2
powershell .\tools\setup_venv.ps1
```

输出:
```
==> 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
```

### 11.2 激活 + 验证

```powershell
.\.venv\Scripts\Activate.ps1
python --version     # Python 3.10.x (venv)
pip list              # 已装的包
ruff check src/       # linter
mypy src/             # 类型检查(部分飘红是 rclpy 缺,忽略)
```

### 11.3 在 venv 里跑纯 Python 测试(不需要 ROS2)

```bash
# 比如写一个纯算法测试
pytest src/<pkg>/test/test_my_algorithm.py
```

### 11.4 完整工作流

```powershell
# 1. 本机开发:venv + IDE
cd D:\xs\ros2
.\.venv\Scripts\Activate.ps1
code .                            # VSCode 打开

# 2. 改完代码,跑容器测试
docker exec ros2_dev bash -lc "cd /root/ros2_ws && colcon build --packages-select <pkg>"
docker exec ros2_dev bash -lc "cd /root/ros2_ws && colcon test --packages-select <pkg>"

# 3. 跑 demo
docker exec ros2_dev bash -lc "source install/setup.bash && ros2 launch bringup <file>"
```

---

## 接下来读

| 主题 | 文档 |
|---|---|
| 项目总览 | [`00-overview.md`](00-overview.md) |
| 5 分钟上手 | [`01-quickstart.md`](01-quickstart.md) |
| 测试策略 | [`90-testing.md`](90-testing.md) |
| Docker | [`85-docker.md`](85-docker.md) |

---

---

## 📖 阅读路径导航

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

- ⏮ **上一篇**: [5 分钟跑通 Hello World](../01-quickstart.md)
- ⏭ **下一篇**: [项目架构 + 设计取舍](../00-overview.md)