xiaoshuai/ROS2_learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
ROS2_learn/doc/02-virtualenv.md
T

7.8 KiB
Raw Permalink Blame History

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

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

目录

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

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

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 已配置好,直接:

{
  "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 测试

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

.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 模块找不到

# 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/:

which python   # /path/.venv/bin/python
which pip      # /path/.venv/bin/pip

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

11. 在本仓库里跑

11.1 创建 venv

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 激活 + 验证

.\.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)

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

11.4 完整工作流

# 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
5 分钟上手 01-quickstart.md
测试策略 90-testing.md
Docker 85-docker.md

📖 阅读路径导航

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

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

Reference in New Issue View Git Blame Copy Permalink