系列： 2026 ROS 2 Lyrical 踩坑实录
环境： Ubuntu 26.04 / WSL2、ROS 2 Lyrical Luth、CMake 4.x
关键词： ROS 2、Lyrical、rosdep、ament_cmake、CMake 4、colcon
前言
把旧版 ROS 2 教程迁移到 Lyrical 时，最容易让人困惑的不是 C++ 代码，而是构建工具链。
本文只整理三个已经实际遇到的高频问题：
pkg_resources is deprecated到底是不是安装失败；Unknown CMake command "ament_target_dependencies"如何修复；- CMake 4.x 为什么拒绝构建旧依赖，以及怎样临时兼容。
文章最后还会给出一套重新编译前的检查顺序，避免在 build/、install/ 和环境变量之间反复绕圈。
一、rosdep 出现 pkg_resources 警告
执行：
rosdep install --from-paths src --ignore-src -r -y --rosdistro lyrical
可能看到：
/usr/bin/rosdep:6: DeprecationWarning: pkg_resources is deprecated as an API
from pkg_resources import load_entry_point
#All required rosdeps installed successfully
这是不是错误？
不是。
判断命令是否成功，应该看最后的执行结果：
#All required rosdeps installed successfully
这说明 rosdep 已经完成依赖解析。前面的内容只是 rosdep 启动脚本调用旧 Python API 产生的弃用警告，不会导致后面的 C++ 功能包编译失败。
不要为了消除一条警告而直接使用 sudo pip 升级系统的 setuptools。这可能覆盖 Ubuntu 由 APT 管理的 Python 软件包，反而导致 rosdep、colcon 或其他系统工具发生依赖冲突。
二、Unknown CMake command "ament_target_dependencies"
1. 完整症状
CMake Error at CMakeLists.txt:17 (ament_target_dependencies):
Unknown CMake command "ament_target_dependencies".
很多旧教程仍然使用：
add_executable(server src/add_two_ints_server.cpp)
ament_target_dependencies(server rclcpp example_interfaces)
在本文的 Lyrical 环境中，find_package(ament_cmake REQUIRED) 没有自动提供这个旧宏，因此 CMake 在配置阶段直接退出。
2. 改用现代 CMake Targets
服务端修改为：
add_executable(server src/add_two_ints_server.cpp)
target_link_libraries(server PRIVATE
rclcpp::rclcpp
${example_interfaces_TARGETS}
)
客户端同样修改：
add_executable(client src/add_two_ints_client.cpp)
target_link_libraries(client PRIVATE
rclcpp::rclcpp
${example_interfaces_TARGETS}
)
这里：
rclcpp::rclcpp是rclcpp导出的现代 CMake Target；${example_interfaces_TARGETS}包含消息和服务接口所需的生成目标；PRIVATE表示这些依赖只用于构建当前可执行文件。
3. 完整 CMakeLists.txt
cmake_minimum_required(VERSION 3.8)
project(lyrical_service_demo)
if(NOT CMAKE_CXX_STANDARD)
set(CMAKE_CXX_STANDARD 17)
endif()
if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
add_compile_options(-Wall -Wextra -Wpedantic)
endif()
find_package(ament_cmake REQUIRED)
find_package(rclcpp REQUIRED)
find_package(example_interfaces REQUIRED)
add_executable(server src/add_two_ints_server.cpp)
target_link_libraries(server PRIVATE
rclcpp::rclcpp
${example_interfaces_TARGETS}
)
add_executable(client src/add_two_ints_client.cpp)
target_link_libraries(client PRIVATE
rclcpp::rclcpp
${example_interfaces_TARGETS}
)
install(TARGETS
server
client
DESTINATION lib/${PROJECT_NAME}
)
ament_package()
4. 修改后清理 CMake 缓存
cd ~/ros2_lyrical_ws
colcon build \
--symlink-install \
--packages-select lyrical_service_demo \
--cmake-clean-cache
--cmake-clean-cache 会让目标包重新执行 CMake 配置，不需要直接删除整个工作空间。
三、CMake 4.x 拒绝构建旧项目
1. 典型错误
Compatibility with CMake < 3.5 has been removed from CMake.
Ubuntu 26.04 使用 CMake 4.x。CMake 4.0 开始移除了对 3.5 以前策略版本的兼容。如果旧项目仍然写着：
cmake_minimum_required(VERSION 2.8)
新版本 CMake 就可能拒绝继续配置。
2. 临时兼容方案
如果这是暂时无法修改的第三方依赖，可以在本次构建中设置最低策略版本：
cd ~/ros2_lyrical_ws
CMAKE_POLICY_VERSION_MINIMUM=3.5 \
colcon build --cmake-clean-cache
也可以传给当前工作空间的 CMake：
colcon build \
--cmake-clean-cache \
--cmake-args -DCMAKE_POLICY_VERSION_MINIMUM=3.5
环境变量会继续传递给构建过程中启动的子进程，因此在 Vendor Package 使用子 CMake 工程时通常更实用。
3. 这不是永久解决方案
它只是让 CMake 暂时按照不低于 3.5 的策略尝试配置。更好的长期方案是：
- 优先升级到支持 CMake 4.x 的依赖版本；
- 如果项目由自己维护，更新
cmake_minimum_required()； - 将兼容性修复提交给上游；
- 修改后重新运行测试，确认没有受到策略变化影响。
四、安装路径与 source 路径不一致
构建成功后，如果 ros2 launch 仍然找不到包，要检查安装路径。
例如构建时使用：
colcon build --install-base /opt/nav2
但终端加载的是：
source ~/nav2_ws/install/setup.bash
这两个目录不是同一个安装空间。应该加载实际安装目录：
source /opt/nav2/setup.bash
确认 ROS 2 当前找到的是哪个包：
ros2 pkg prefix <package_name>
如果修改了安装位置，还应检查 .bashrc 是否仍在加载旧工作空间，避免 Overlay 与 Underlay 混用。
五、推荐的编译排错顺序
# 1. 加载基础环境
source /opt/ros/lyrical/setup.bash
# 2. 确认发行版
echo $ROS_DISTRO
# 3. 安装依赖
rosdep install --from-paths src --ignore-src -r -y --rosdistro lyrical
# 4. 只编译目标包并刷新缓存
colcon build \
--symlink-install \
--packages-select lyrical_service_demo \
--cmake-clean-cache
# 5. 加载本次构建结果
source install/setup.bash
# 6. 检查包和可执行文件
ros2 pkg prefix lyrical_service_demo
ros2 pkg executables lyrical_service_demo
一次只改变一个条件，比同时修改依赖、环境变量和 CMake 文件更容易找到真正的根因。
六、总结
这次排错最重要的经验可以压缩成四句话：
DeprecationWarning不等于执行失败，要看最终结果；- Lyrical 新项目优先使用现代 CMake Targets；
- CMake 4.x 不再兼容低于 3.5 的旧策略版本；
- 构建目录、安装目录和
source路径必须一致。
参考资料
- CMake：
CMAKE_POLICY_VERSION_MINIMUM
cmake.org/cmake/help/… - CMake：
cmake_minimum_required
cmake.org/cmake/help/… - ament_cmake：Modern CMake Targets 讨论
github.com/ament/ament…
