📚 课程目录第3章开发环境搭建

3. 开发环境搭建

在开始ROS2机器人视觉AI部署之前，一套干净、可复现且版本匹配的开发环境是决定项目成败的基石。本章节将围绕“从零搭建”这一目标，系统讲解ROS2（以Humble Hawksbill为例，适配Ubuntu 22.04）的安装策略、工作空间的结构化配置方法，以及摄像头驱动与推理引擎（OpenCV、TensorRT、ONNX Runtime）的安装细节与版本匹配原则。我们不仅要解决“怎么装”，更要理解“为什么这样装”，从而避免在后续开发中陷入依赖地狱或性能瓶颈。

上图展示了ROS2视觉AI部署的三层架构：系统层、中间件与驱动层、推理与算法层。每一层都有其独立的版本约束和依赖关系，而层与层之间的接口（如话题通信、张量内存格式）则是集成时的关键风险点。下面我们将按照实际操作顺序，逐步展开每个环节的具体配置方法。

3.1 核心原理：为什么版本匹配比安装本身更重要

在ROS2生态中，二进制接口（ABI）兼容性和CUDA运行时依赖是两大核心约束。ROS2 Humble基于Ubuntu 22.04构建，其默认编译器为GCC 11.2，Python版本为3.10。如果你手动编译OpenCV或TensorRT时使用了不同版本的GCC或Python，生成的库文件在运行时可能因符号解析失败而崩溃。

推理引擎的版本匹配更为敏感。TensorRT的每个版本都对应特定的CUDA和cuDNN版本。例如，TensorRT 8.5.3要求CUDA 11.8和cuDNN 8.6。如果系统安装的是CUDA 12.0，即使TensorRT能勉强加载，在构建engine文件时也会抛出“Unsupported CUDA version”错误。ONNX Runtime的CUDA Execution Provider同样需要与CUDA运行时严格对应，否则会在初始化时报告“Failed to load CUDA shared library”。

因此，我们的安装策略是：先确定CUDA版本，再选择TensorRT和ONNX Runtime版本，最后编译OpenCV。这种自底向上的顺序能最大程度减少版本冲突。

版本选型参考表（已验证组合）

组件	推荐版本	关键依赖	适用场景
Ubuntu	22.04.3 LTS	内核 5.15	ROS2 Humble官方支持
ROS2	Humble Hawksbill	Python 3.10, GCC 11.2	LTS版本，支持至2027年
CUDA	11.8	NVIDIA驱动 ≥ 520	TensorRT 8.5/8.6 最佳搭配
TensorRT	8.5.3	CUDA 11.8, cuDNN 8.6	FP16/INT8 高性能推理
ONNX Runtime	1.14.0	CUDA 11.8, cuDNN 8.6	跨框架模型转换与部署
OpenCV	4.6.0	libv4l, ffmpeg	图像采集与预处理

3.2 操作流程：从裸机到可用推理环境的四步走

以下操作均在终端中完成，建议全程使用sudo权限或配置好sudo免密。我们将分为四个阶段：基础系统配置、ROS2安装、摄像头驱动验证、推理依赖安装。

阶段一：基础系统配置

# 1. 更换软件源为国内镜像（可选但推荐）
sudo sed -i 's@//.*archive.ubuntu.com@//mirrors.aliyun.com@g' /etc/apt/sources.list
sudo apt update && sudo apt upgrade -y

# 2. 安装基础开发工具
sudo apt install -y build-essential cmake git python3-pip python3-venv \
    net-tools curl wget gnupg lsb-release

# 3. 安装NVIDIA驱动（若使用GPU推理）
# 先检测推荐驱动版本
ubuntu-drivers devices
sudo apt install -y nvidia-driver-535  # 以实际推荐为准
# 重启后验证
nvidia-smi  # 应显示驱动版本和CUDA版本（此时为驱动自带CUDA）

风险提示：安装NVIDIA驱动前务必确认内核版本与驱动兼容性。若驱动安装失败导致无法进入图形界面，可在恢复模式下手动卸载驱动（sudo apt purge nvidia-*）。建议在纯命令行服务器环境操作，避免桌面环境干扰。

阶段二：安装ROS2 Humble

# 1. 设置编码
sudo apt update && sudo apt install -y locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

# 2. 添加ROS2源
sudo apt install -y software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install -y curl
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 $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

# 3. 安装ROS2基础版（桌面版可加ros-humble-desktop）
sudo apt update
sudo apt install -y ros-humble-ros-base ros-dev-tools

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

# 5. 验证安装
ros2 --help
ros2 topic list  # 应显示 /parameter_events 和 /rosout

阶段三：配置工作空间

工作空间采用标准的colcon布局，包含src（源码）、build（编译中间文件）、install（安装产物）、log（日志）四个目录。

mkdir -p ~/robot_ws/src
cd ~/robot_ws
# 若尚未安装colcon
sudo apt install -y python3-colcon-common-extensions

# 创建一个测试包验证环境
cd ~/robot_ws/src
ros2 pkg create --build-type ament_cmake test_pkg
cd ~/robot_ws
colcon build --symlink-install
source install/setup.bash
ros2 pkg list | grep test_pkg  # 应能看到test_pkg

经验提示：使用--symlink-install参数可以创建符号链接，后续修改Python脚本或launch文件时无需重新编译，极大提升开发效率。对于C++节点，修改头文件后仍需重新编译。

阶段四：安装摄像头驱动与推理依赖

摄像头驱动分为USB摄像头（UVC协议）和CSI摄像头（树莓派或Jetson）。我们以最常见的USB摄像头为例。

# 1. 安装v4l2工具和ROS2摄像头驱动包
sudo apt install -y v4l-utils ros-humble-camera-calibration ros-humble-usb-cam
# 验证摄像头识别
lsusb  # 查看USB设备
v4l2-ctl --list-devices  # 应显示 /dev/video0

# 2. 安装OpenCV（使用apt版本，保证与ROS2兼容）
sudo apt install -y libopencv-dev python3-opencv
# 验证
python3 -c "import cv2; print(cv2.__version__)"  # 应输出 4.6.0

# 3. 安装CUDA 11.8（若使用GPU推理）
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run
sudo sh cuda_11.8.0_520.61.05_linux.run --toolkit --silent --override
# 配置环境变量
echo 'export PATH=/usr/local/cuda-11.8/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
nvcc --version  # 验证CUDA

# 4. 安装TensorRT 8.5.3（需从NVIDIA官网下载deb包）
# 下载后执行：
sudo dpkg -i nv-tensorrt-repo-ubuntu2204-cuda11.8-trt8.5.3.1-ga-20230314_1-1_amd64.deb
sudo apt update
sudo apt install -y tensorrt
# 验证
python3 -c "import tensorrt; print(tensorrt.__version__)"  # 应输出 8.5.3.1

# 5. 安装ONNX Runtime 1.14.0（pip安装GPU版本）
pip3 install onnxruntime-gpu==1.14.0
python3 -c "import onnxruntime as ort; print(ort.__version__)"  # 应输出 1.14.0

3.3 案例拆解：一次典型的摄像头推理节点部署

下面我们通过一个实际案例，将上述环境串联起来。假设我们有一个YOLOv5s的ONNX模型，需要在ROS2节点中实时推理USB摄像头画面。

场景约束：

硬件：Intel i7-12700 + NVIDIA RTX 3060，USB 3.0摄像头（1080p@30fps）
目标：推理延迟 < 30ms，CPU占用 < 50%
初始现象：直接使用ONNX Runtime CPU执行，推理延迟约120ms，无法满足实时性

分析过程：

首先确认摄像头采集延迟：使用ros2 run usb_cam usb_cam_node_exe发布话题，通过rqt_graph确认图像话题频率稳定在30Hz。
检查推理瓶颈：使用ONNX Runtime的CPU Execution Provider，发现模型输入为640x640x3，单次推理耗时120ms。瓶颈在卷积计算。
切换到CUDA Execution Provider：修改代码中SessionOptions，添加CUDAExecutionProvider，推理延迟降至15ms。
进一步优化：启用TensorRT Execution Provider（需先转换为TensorRT engine），延迟降至8ms，满足要求。

关键代码片段（Python）：

import onnxruntime as ort
import numpy as np
import cv2
from sensor_msgs.msg import Image
import rclpy
from rclpy.node import Node

class InferenceNode(Node):
    def __init__(self):
        super().__init__('inference_node')
        self.sub = self.create_subscription(Image, '/image_raw', self.callback, 10)
        self.pub = self.create_publisher(Image, '/inference_result', 10)
        # 创建ONNX Runtime会话，优先使用TensorRT，其次CUDA
        providers = [
            ('TensorrtExecutionProvider', {'device_id': 0, 'trt_fp16_enable': True}),
            'CUDAExecutionProvider',
            'CPUExecutionProvider'
        ]
        self.session = ort.InferenceSession('yolov5s.onnx', providers=providers)
        self.get_logger().info(f'Using providers: {self.session.get_providers()}')

    def callback(self, msg):
        # 将ROS图像转为numpy数组
        img = np.frombuffer(msg.data, dtype=np.uint8).reshape(msg.height, msg.width, -1)
        img = cv2.cvtColor(img, cv2.COLOR_RGB2BGR)
        # 预处理：resize到640x640，归一化
        input_tensor = self.preprocess(img)
        # 推理
        outputs = self.session.run(None, {'images': input_tensor})
        # 后处理并发布结果（此处省略NMS等）
        result_msg = self.postprocess(outputs, msg)
        self.pub.publish(result_msg)

    def preprocess(self, img):
        img = cv2.resize(img, (640, 640))
        img = img.astype(np.float32) / 255.0
        img = np.transpose(img, (2, 0, 1))[None, ...]
        return img

    def postprocess(self, outputs, original_msg):
        # 简化处理：仅返回原图
        return original_msg

结果对比：

Execution Provider	推理延迟	CPU占用	GPU显存	是否满足实时
CPU	120ms	85%	0MB	否
CUDA	15ms	20%	1.2GB	是
TensorRT FP16	8ms	15%	0.8GB	是（最优）

复盘经验：在GPU推理场景中，TensorRT的FP16优化能带来近2倍性能提升，但需要额外的模型转换时间（约30秒）。对于需要频繁更新模型的场景，建议保留ONNX Runtime的CUDA路径作为回退方案。此外，摄像头采集与推理节点应分离部署，避免图像传输阻塞推理线程。

3.4 常见误区与总结复盘

在环境搭建过程中，以下问题出现频率最高，需要特别警惕：

误区一：盲目使用最新版本。最新版TensorRT（如10.x）可能不支持ROS2 Humble自带的CUDA 11.8，导致编译失败。务必使用与CUDA版本匹配的TensorRT 8.5/8.6。

误区二：忽略OpenCV的CUDA支持。默认apt安装的OpenCV不包含CUDA模块（如cv2.cuda），若需在GPU上做图像预处理，必须从源码编译OpenCV并开启WITH_CUDA=ON。但源码编译耗时较长（约1小时），建议评估是否真的需要。

误区三：工作空间环境变量覆盖。当同时source了ROS2和自定义工作空间时，后source的会覆盖前者的环境变量。建议在~/.bashrc中只保留ROS2的source，工作空间的source在需要时手动执行。

误区四：摄像头权限问题。USB摄像头设备文件/dev/video0默认属于video组，当前用户需加入该组才能访问：sudo usermod -aG video $USER，然后重新登录。

总结复盘清单：

版本锁定：在项目根目录创建requirements.txt或environment.yaml，记录所有关键依赖的精确版本号，便于复现。
分层验证：每安装一个组件，立即执行对应的验证命令（如ros2 topic list、python3 -c "import cv2"），避免问题堆积。
性能基线：在部署推理节点前，先单独测试摄像头采集延迟和推理引擎延迟，建立性能基线，便于后续定位瓶颈。
备份策略：使用Docker或VMware快照保存配置好的环境，一旦系统损坏可快速恢复。推荐使用docker pull ros:humble作为基础镜像，再叠加推理依赖。

通过本章节的系统搭建，你已经拥有了一个具备摄像头采集、图像处理、GPU加速推理能力的完整开发环境。下一阶段，我们将基于此环境编写第一个ROS2视觉节点，实现图像话题的发布与订阅。