Ubuntu 22.04 ROS2 Humble 源码编译安装 teb_local_planner 踩坑记录

引言

最近需要在 ROS2 Humble 环境下使用 teb_local_planner 进行局部路径规划，本以为可以像 ROS1 那样直接用 apt 安装，结果发现 ros-humble-teb-local-planner 包并不存在于官方源中。只好选择源码编译，过程中遇到了不少坑，特此记录，希望能帮助到有同样需求的朋友。

环境

操作系统：Ubuntu 22.04.3 LTS
ROS2 发行版：Humble Hawksbill（已安装桌面版）
工作空间：~/teb_ws

一、尝试 apt 安装（失败）

bash 复制代码

sudo apt install ros-humble-teb-local-planner

报错：E: 无法定位软件包 ros-humble-teb-local-planner。果然没有预编译包，只能源码编译。

二、准备源码

创建并进入工作空间：

bash 复制代码

mkdir -p ~/teb_ws/src
cd ~/teb_ws/src

克隆 teb_local_planner 及其依赖 costmap_converter（注意分支，Humble 对应 ros2 或 ros2-humble）：

bash 复制代码

git clone https://github.com/rst-tu-dortmund/costmap_converter.git -b ros2
git clone https://github.com/rst-tu-dortmund/teb_local_planner.git -b ros2-master

三、安装依赖

先确保 ROS2 环境已加载：

bash 复制代码

source /opt/ros/humble/setup.bash

使用 rosdepc 自动安装大部分依赖：

（我用的是鱼香ROS的rosdepc，如果自己没有用过，那就把rosdepc改称rosdep）

bash 复制代码

cd ~/teb_ws
rosdepc install -i --from-path src --rosdistro humble -y

手动补充一些系统库：

bash 复制代码

sudo apt install libsuitesparse-dev libeigen3-dev

安装 g2o 时发现 libg2o-dev 不存在，搜索后发现 Humble 中提供了 ROS 打包的版本：

bash 复制代码

sudo apt install ros-humble-libg2o

四、编译 costmap_converter（第一个大坑）

开始编译：

bash 复制代码

colcon build --packages-select costmap_converter

报错：

复制代码

fatal error: cv_bridge/cv_bridge.hpp: 没有那个文件或目录

明明已经安装了 ros-humble-cv-bridge，为什么找不到？检查发现头文件实际位置是 /opt/ros/humble/include/cv_bridge/cv_bridge/cv_bridge.h（注意多了一层 cv_bridge 子目录），而代码中引用的是 <cv_bridge/cv_bridge.hpp>，路径和文件名都不匹配。

解决方案

方法一：修改源代码中的 #include 语句（推荐，一劳永逸）

bash 复制代码

sed -i 's/#include <cv_bridge\/cv_bridge.hpp>/#include <cv_bridge\/cv_bridge\/cv_bridge.h>/g' ~/teb_ws/src/costmap_converter/costmap_converter/include/costmap_converter/costmap_to_dynamic_obstacles/*.h

方法二：修改 CMakeLists.txt，手动添加包含目录

在 costmap_converter/CMakeLists.txt 中，找到 add_library 之后添加：

cmake 复制代码

target_include_directories(costmap_converter PRIVATE /opt/ros/humble/include/cv_bridge)
target_link_libraries(costmap_converter ${cv_bridge_LIBRARIES})

修改后重新编译，costmap_converter 成功通过。

五、编译 teb_local_planner（更多坑）

接着编译 teb_local_planner：

bash 复制代码

colcon build --packages-select teb_local_planner

问题1：nav2_core/controller_exceptions.hpp 找不到

错误信息：

复制代码

fatal error: nav2_core/controller_exceptions.hpp: 没有那个文件或目录

在 Humble 中，nav2_core 的头文件结构变了：异常类移到了 exceptions.hpp，控制器基类在 controller.hpp。需要修改 teb_local_planner_ros.cpp 中的头文件引用：

cpp 复制代码

// 原来
#include <nav2_core/controller_exceptions.hpp>

// 改为
#include <nav2_core/controller.hpp>
#include <nav2_core/exceptions.hpp>

问题2：calculateMinAndMaxDistances 函数调用错误

错误信息：

复制代码

error: too few arguments to function 'void nav2_costmap_2d::calculateMinAndMaxDistances(...)'

该函数在 Humble 中返回类型是 void，通过输出参数返回，而原代码试图用 std::tie 接收返回值。需要修改两处调用：

在 initialize 函数中（约第154行）：

原代码：

cpp 复制代码

std::tie(robot_inscribed_radius_, robot_circumscribed_radius) = nav2_costmap_2d::calculateMinAndMaxDistances(footprint_spec_);

修改为：

cpp 复制代码

nav2_costmap_2d::calculateMinAndMaxDistances(footprint_spec_, robot_inscribed_radius_, robot_circumscribed_radius);

在 computeVelocityCommands 函数中（约第392行）：

原代码：

cpp 复制代码

std::tie(robot_inscribed_radius_, robot_circumscribed_radius) = nav2_costmap_2d::calculateMinAndMaxDistances(updated_footprint_spec_);

修改为：

cpp 复制代码

nav2_costmap_2d::calculateMinAndMaxDistances(updated_footprint_spec_, robot_inscribed_radius_, robot_circumscribed_radius);

问题3：nav2_core::ControllerException 未定义

尽管已经包含了 exceptions.hpp，但编译器仍然报错 ControllerException 不是 nav2_core 的成员。查阅资料发现可能是 Humble 中该异常类的命名空间或定义方式有变。为了快速解决，我们统一改用标准异常 std::runtime_error。

在文件顶部添加 #include <stdexcept>，然后用 sed 批量替换：

bash 复制代码

sed -i 's/throw nav2_core::ControllerException(/throw std::runtime_error(/g' ~/teb_ws/src/teb_local_planner/teb_local_planner/src/teb_local_planner_ros.cpp

六、最终编译成功

再次执行：

bash 复制代码

colcon build --packages-select teb_local_planner

终于看到绿色的 Finished <<< teb_local_planner！

验证安装：

bash 复制代码

source ~/teb_ws/install/setup.bash
ros2 pkg list | grep teb_local_planner

输出 teb_local_planner，成功！

总结与建议

不要尝试 apt 安装，Humble 没有预编译包。
分支选择很重要 ，使用 ros2 分支（或 ros2-humble）与 Humble 兼容性较好。
头文件路径问题 是 ROS2 迁移过程中的常见坑，遇到类似错误可以先用 find 查找头文件实际位置，然后调整 #include 或 CMakeLists.txt。
Nav2 API 变化 需要手动适配，特别是 calculateMinAndMaxDistances 和异常类的变化。
如果异常类找不到 ，可以临时改用 std::runtime_error，不影响功能。

虽然过程曲折，但最终 teb_local_planner 成功运行在 Humble 上。希望官方后续能提供更完善的二进制包，或更新文档说明。如果你也遇到了类似问题，按照本文步骤操作，应该能顺利通过。