Ubuntu 24.04 + ROS2 Jazzy 开发环境避坑指南

️ 环境配置（仅需操作一次）

前提背景：Ubuntu 24.04 强制要求使用虚拟环境安装 pip 第三方库，而 ROS2 编译工具链（colcon, catkin_pkg）依赖系统全局 Python。为兼顾两者，需创建一个“能看见系统 ROS2 库”的虚拟环境。

1. 进入工作空间根目录（例如 topic_ws/）。
2. 创建关联全局包的虚拟环境（关键步骤：--system-site-packages）：

   python3 -m venv .venv --system-site-packages
   

3. 手动补充 ROS2 核心库软连接（确保虚拟环境能 100% 识别 ROS2 库）：

   source .venv/bin/activate
   ln -s /opt/ros/jazzy/lib/python3.12/site-packages/* .venv/lib/python3.12/site-packages/
   deactivate
   

4. 安装项目所需的第三方库：

   source .venv/bin/activate
   pip install numpy transforms3d  # 按需安装
   deactivate
   

日常开发标准流程（每次编译/运行）

核心原则：colcon build 必须在系统全局环境（退出虚拟环境）下进行；ros2 run 运行 Python 节点时再激活虚拟环境。

1. 编译阶段（C++ 和 Python 包通用）

# 确保不在虚拟环境中（前面没有 .venv 标识）
deactivate 

# 加载 ROS2 系统环境并编译
source /opt/ros/jazzy/setup.bash
colcon build --packages-select <你的功能包名>
source install/setup.bash

2. 运行阶段

• 运行 C++ 节点（无需虚拟环境）：

  source /opt/ros/jazzy/setup.bash
  source install/setup.bash
  ros2 run <包名> <节点名>
  

• 运行 Python 节点（需激活虚拟环境）：

  source .venv/bin/activate            # 激活虚拟环境（加载 numpy 等第三方库）
  source /opt/ros/jazzy/setup.bash     # 加载 ROS2 环境
  #动态获取虚拟环境路径并加入 PYTHONPATH，解决 ROS2 找不到虚拟环境中第三方库的问题
  export PYTHONPATH="$(python -c 'import sysconfig; print(sysconfig.get_path("purelib"))'):$PYTHONPATH"    
  source install/setup.bash            # 加载工作空间
  ros2 run <包名> <节点名>
  

按照以上步骤操作，即可完美解决 Ubuntu 24.04 下 ROS2 的 Python 依赖冲突问题。