📚 课程目录第2章环境搭建

2. 环境搭建

2.1 核心原理：为什么环境搭建决定项目成败

ROS2控制器节点项目的开发，本质上是在一个分布式通信框架中组织多个可执行程序。环境搭建的核心目标，是让编译器、依赖库、运行时环境和构建工具形成一个闭环。与普通C++工程不同，ROS2项目依赖ament构建系统、rclcpp客户端库以及rmw中间件实现层，这些组件版本必须严格匹配。例如，Ubuntu 22.04对应ROS2 Humble，Ubuntu 24.04对应Jazzy，混用版本会导致ABI不兼容，出现段错误或符号找不到等诡异问题。

工作空间（Workspace）是ROS2的源码组织单元，其核心原理是叠加（Overlay）机制：底层安装的ROS2作为underlay，用户创建的src目录作为overlay，构建后生成install目录。每次修改源码后，只需重新构建当前包，而不必重装整个系统。依赖配置则通过package.xml声明构建依赖（build_depend）和运行依赖（exec_depend），由rosdep工具自动解析并安装系统级库。

2.2 方法流程：从零到可运行的四步走

2.2.1 安装ROS2发行版

以Ubuntu 22.04 + ROS2 Humble为例，安装过程分为软件源配置、密钥添加、核心包安装、环境变量加载四个环节。首先需要确保系统支持UTF-8编码，并启用universe软件源。安装完成后，必须将ROS2的环境变量写入~/.bashrc，否则每次打开新终端都需要手动source。

# 1. 设置软件源
sudo apt update && sudo apt install -y curl gnupg lsb-release
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

# 2. 安装ROS2 Humble桌面版（包含可视化工具）
sudo apt update
sudo apt install -y ros-humble-desktop python3-argcomplete

# 3. 配置环境变量
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

# 4. 验证安装
ros2 --version   # 应输出 ros2 版本号
printenv | grep ROS_DISTRO  # 应输出 humble

2.2.2 创建工作空间与功能包

工作空间命名建议使用dev_ws（development workspace），内部必须包含src目录。创建功能包时，推荐使用ament_cmake构建类型，因为控制器节点通常需要编译C++源码。功能包名称必须使用小写字母和下划线，不能包含连字符或大写字母。

# 创建工作空间
mkdir -p ~/dev_ws/src
cd ~/dev_ws/src

# 创建控制器节点功能包（示例：robot_controller）
ros2 pkg create robot_controller \
  --build-type ament_cmake \
  --dependencies rclcpp geometry_msgs nav_msgs \
  --license Apache-2.0

# 编译工作空间
cd ~/dev_ws
colcon build --symlink-install
source install/setup.bash

2.2.3 依赖配置与rosdep使用

当功能包需要外部系统库（如Eigen、OpenCV）时，必须通过rosdep自动安装。首先初始化rosdep，然后使用rosdep install命令解析package.xml中的依赖声明。对于控制器节点，常见的依赖包括tf2（坐标变换）、control_msgs（控制消息）和realtime_tools（实时控制工具）。

# 初始化rosdep（首次使用）
sudo rosdep init
rosdep update

# 在工作空间根目录安装所有缺失依赖
cd ~/dev_ws
rosdep install --from-paths src --ignore-src -r -y

# 手动安装常用控制库（若rosdep未覆盖）
sudo apt install -y ros-humble-ros2-control ros-humble-ros2-controllers

2.3 案例：搭建一个带PID控制器的节点环境

假设我们需要开发一个轮式机器人速度控制器节点，其依赖关系比默认模板复杂得多。下面展示一个真实的package.xml配置片段，以及对应的CMakeLists关键设置。

<!-- package.xml 关键依赖声明 -->
<depend>rclcpp</depend>
<depend>geometry_msgs</depend>
<depend>nav_msgs</depend>
<depend>tf2_ros</depend>
<depend>control_msgs</depend>
<depend>realtime_tools</depend>
<build_depend>eigen</build_depend>
<exec_depend>ros2launch</exec_depend>

# CMakeLists.txt 中链接Eigen和ament依赖
find_package(Eigen3 REQUIRED)
find_package(rclcpp REQUIRED)
find_package(geometry_msgs REQUIRED)
find_package(nav_msgs REQUIRED)
find_package(tf2_ros REQUIRED)
find_package(control_msgs REQUIRED)
find_package(realtime_tools REQUIRED)

ament_target_dependencies(robot_controller_node
  rclcpp geometry_msgs nav_msgs tf2_ros control_msgs realtime_tools)

target_include_directories(robot_controller_node PRIVATE
  ${EIGEN3_INCLUDE_DIR} src/include)

完成上述配置后，执行colcon build --packages-select robot_controller即可单独编译该包。若编译过程中出现Could not find a package configuration file错误，说明缺少对应依赖，需回到rosdep install步骤排查。

2.4 常见误区与复盘

误区现象	根本原因	正确做法
运行`ros2 run`提示找不到包	未source install/setup.bash，或工作空间未编译	每次新终端执行`source ~/dev_ws/install/setup.bash`
编译时出现`undefined reference`	CMakeLists中缺少`ament_target_dependencies`声明	检查所有头文件对应的依赖包是否已声明
rosdep update超时	网络问题或rosdep未初始化	使用代理，或手动`sudo apt install`缺失库
Python节点无法导入rclpy	系统默认Python版本与ROS2不匹配	使用`python3`显式运行，避免虚拟环境干扰

重要提醒：不要使用sudo colcon build编译工作空间。这会导致生成的install目录归属root用户，后续普通用户无法正常source，且可能污染系统级ROS2安装。如果误操作，请使用sudo rm -rf build install log后重新以普通用户编译。

效率技巧：在~/.bashrc中添加以下别名，可大幅提升日常操作效率：

alias cb='cd ~/dev_ws && colcon build --symlink-install'
alias cbs='cd ~/dev_ws && colcon build --symlink-install --packages-select'
alias sb='source ~/dev_ws/install/setup.bash'

2.5 环境验证清单

完成所有配置后，建议按以下清单逐项验证，确保环境无隐患：

版本一致性：ros2 --version输出包含humble，且echo $ROS_DISTRO返回humble。
工作空间叠加：在~/dev_ws下执行printenv | grep AMENT_PREFIX_PATH，应同时看到/opt/ros/humble和~/dev_ws/install两个路径。
依赖完整性：rosdep check --from-paths src --ignore-src输出无缺失项。
编译测试：新建临时测试包并编译，确认colcon build无报错，ros2 pkg list | grep 包名能查到该包。
通信测试：终端A运行ros2 run demo_nodes_cpp talker，终端B运行ros2 run demo_nodes_cpp listener，能收到Hello World消息。

环境搭建是ROS2开发中最容易踩坑的环节，但也是回报率最高的投资。一个干净、可复现的环境，能让你在后续编写控制器节点时，将精力完全集中在算法和逻辑上，而不是浪费在排查链接错误或版本冲突上。建议将上述安装命令保存为setup_ros2.sh脚本，配合README.md记录环境版本，便于团队协作时快速复现。