一、ros2 pkg list功能说明

作用

扫描并列出系统中所有 ROS2 功能包（package）。

bash

运行

ros2 pkg list # 过滤查找某个包 ros2 pkg list | grep yahboom

配套常用命令：

bash

运行

ros2 pkg describe 包名 # 查看包信息 ros2 pkg executables 包名 # 查看包内可执行文件

二、核心问题：ROS2 依靠什么找到所有功能包？

核心机制：AMENT_PREFIX_PATH环境变量

ROS2不会全局扫描硬盘，完全依靠环境变量定位包。

1. 原理拆解

1. 每个 ROS2 功能包编译安装后，文件夹内一定存在一个标记文件：package.xml只要一个目录包含合法package.xml，它就是一个 ROS2 package。

2. AMENT_PREFIX_PATH保存一系列目录路径格式示例：

plaintext

/opt/ros/humble /home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install

• /opt/ros/humble：系统预装 ROS 官方包（joy、rclcpp、rclpy 等）
• xxx/install：你自己工作空间编译出来的自定义包

1. 当执行ros2 pkg list： ROS2 底层 ament 工具循环遍历AMENT_PREFIX_PATH里每一条路径在每一条路径下搜寻share/*/package.xml每找到一个合法package.xml→ 识别为 1 个功能包，汇总展示。

目录标准布局（install 目录内部）

plaintext

install/yahboomcar_ctrl/ ├─ share/ │ └─ yahboomcar_ctrl/ │ └─ package.xml ←【识别功能包的核心凭证】 └─ lib/

✅ 关键点：必须存在 share/<包名>/package.xml

三、延伸：source 命令在这里扮演什么角色？

执行：

bash

运行

source install/setup.bash

这条命令本质就是：把当前工作空间的 install 路径追加到AMENT_PREFIX_PATH

举个时序例子（小车开发流程）

1. 编译colcon build→ 文件输出到./install
2. source install/setup.bash→ 将~/yahboomcar_ws/install写入环境变量AMENT_PREFIX_PATH
3. ros2 pkg list扫描环境变量内路径 → 发现 yahboomcar_ctrl

❗新开终端默认没有这条路径，所以找不到自己编译的包，必须 source！

四、容易混淆的几个关键点

1. ROS2 不扫描 src 源码目录！src下面的源码哪怕有 package.xml，如果没有编译 + source，`ros2 pkg list看不到。 它只读取install 目录，不读取源码。

2. 环境变量叠加顺序（覆盖优先级）AMENT_PREFIX_PATH靠前路径优先

plaintext

/workspace/install:/opt/ros/humble

自定义工作空间在前 → 可以覆盖系统同名功能包（overlay 工作空间机制）

1. 如何查看当前搜索路径（验证）

bash

运行

echo $AMENT_PREFIX_PATH

五、极简总结

1. ros2 pkg list：遍历AMENT_PREFIX_PATH内所有路径，搜寻share/*/package.xml，输出所有识别到的功能包。
2. ROS 识别功能包两大必要条件：
   • 路径被写入AMENT_PREFIX_PATH
   • 路径下存在合法share/包名/package.xml
3. source setup.bash的核心作用：将工作空间 install 目录添加进AMENT_PREFIX_PATH。

补充调试命令（方便你排查找不到包的问题）

bash

运行

# 查看当前包搜索路径 echo $AMENT_PREFIX_PATH # 只查看某个路径下的包（底层ament原生工具） ament_packages find /home/sunrise/xxx/install

sunrise@ubuntu:~$ echo AMENT_PREFIX_PATH
AMENT_PREFIX_PATH
sunrise@ubuntu:~$ echo $AMENT_PREFIX_PATH
/home/sunrise/workspce_test/src/install/pkg_helloworld_py:/home/sunrise/workspce_test/src/install/pkg_helloworld_cpp:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/ydlidar_ros2_driver:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/web_video_server:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/usb_cam:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/teb_local_planner:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/teb_msgs:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/sllidar_ros2:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/slam_gmapping:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/robot_localization:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/openslam_gmapping:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/costmap_converter:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/costmap_converter_msgs:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/cartographer_rviz:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/cartographer_ros:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/cartographer_ros_msgs:/home/sunrise/yahboomcar_ros2_ws/software/library_ws/install/ascamera:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_web_savmap_interfaces:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_voice_ctrl_depth:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_voice_ctrl:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_vision:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_nav:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_multi:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_msgs:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_mediapipe:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_laser:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_description:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_depth:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_ctrl:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_bringup:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_base_node:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_astra:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/yahboomcar_app_save_map:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/text_chat:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/robot_pose_publisher_ros2:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/multi_brains:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/laserscan_to_point_publisher:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/largemodel:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/interfaces:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/auto_interfaces:/home/sunrise/yahboomcar_ros2_ws/yahboomcar_ws/install/auto_drive:/opt/ros/humble
sunrise@ubuntu:~$