ROS2 自定义消息接口：msg / srv / action 的编写与编译
2026/11/6...大约 3 分钟
ROS2 自定义消息接口（接口定制）
核心结论
三种通信方式各有自己的接口文件：话题用
.msg、服务用.srv、动作用.action。三者共用同一套生成机制（rosidl），差别只在文件里用分隔符分成几段，以及package.xml里多写几个依赖。流程固定四步：写接口文件 → 改
package.xml与CMakeLists.txt→colcon build→ros2 interface show验证。
什么时候需要自定义
| 方案 | 适用 | 局限 |
|---|---|---|
std_msgs 原生类型（String / Int32 / Float64 …） | 只传单个值 | 只有一个 data 字段，结构太单薄 |
标准接口（sensor_msgs 点云/图像、geometry_msgs 坐标/速度…） | 常见传感器与几何数据 | 覆盖不到业务字段 |
| 自定义接口 | 业务结构（学生信息、加法请求、进度反馈…） | 需要自己建接口包、配置、编译 |
一、准备接口功能包
接口文件必须放在一个独立的功能包里，业务包通过依赖引用它：
mkdir -p ws01_plumbing/src && cd ws01_plumbing/src
colcon build
ros2 pkg create --build-type ament_cmake base_interfaces_demo
# 业务包依赖接口包
ros2 pkg create cpp01_topic --build-type ament_cmake --dependencies rclcpp std_msgs base_interfaces_demo
ros2 pkg create py01_topic --build-type ament_python --dependencies rclpy std_msgs base_interfaces_demo二、三种接口文件
.msg（话题）
msg/Student.msg：
string name
int32 age
float64 height.srv（服务）
srv/AddInts.srv —— --- 上为请求，下为响应：
int32 num1
int32 num2
---
int32 sum.action（动作）
action/Progress.action —— 两个 --- 分成三段：目标、结果、反馈：
int64 num
---
int64 sum
---
float64 progress三、配置 package.xml
.msg / .srv 用：
<build_depend>rosidl_default_generators</build_depend>
<exec_depend>rosidl_default_runtime</exec_depend>
<member_of_group>rosidl_interface_packages</member_of_group>.action 有两处不同，是最常见的编译失败原因：
<!-- 注意：是 buildtool_depend，不是 build_depend -->
<buildtool_depend>rosidl_default_generators</buildtool_depend>
<depend>action_msgs</depend>
<member_of_group>rosidl_interface_packages</member_of_group>- 同一个接口包里已经有
msg时，不需要重复rosidl_default_runtime，只新增action那两行； member_of_group声明本包属于接口包组，缺了它生成器不会处理这些文件。
四、配置 CMakeLists.txt
find_package(rosidl_default_generators REQUIRED)
rosidl_generate_interfaces(${PROJECT_NAME}
"msg/Student.msg"
"srv/AddInts.srv"
"action/Progress.action"
)一个包里多种接口就是在一个 rosidl_generate_interfaces() 里多列几行，不要写多个函数调用。
五、编译与验证
colcon build --packages-select base_interfaces_demo
. install/setup.bash
ros2 interface show base_interfaces_demo/msg/Student
ros2 interface show base_interfaces_demo/srv/AddInts
ros2 interface show base_interfaces_demo/action/Progress编译成功后，install/ 下会生成对应的 C++ 头文件与 Python 模块，ros2 interface show 能打印出结构即说明生成链路通了。
六、两个编辑器配置（省掉"找不到头文件"的假故障）
C++ 侧 c_cpp_properties.json 的 includePath 加：
"${workspaceFolder}/install/base_interfaces_demo/include/**"Python 侧 settings.json 的 python.autoComplete.extraPaths 与 python.analysis.extraPaths 加：
"${workspaceFolder}/install/base_interfaces_demo/lib/python3.12/site-packages"Python 路径里的版本号随 ROS2 发行版变化（Jazzy 是 3.12），按自己的 install/ 目录结构改。这两个配置只影响 IDE 补全/高亮，不改的话 colcon build 仍然能过。