ROS自定义msg完全指南：从定义、编译到C++/Python收发实践

在ROS里跑过几个demo之后，你会很快发现一个尴尬事：官方那套消息类型，翻来覆去就是Twist、Pose、Odometry，想传个结构化数据——比如一个学生的姓名、学号、成绩、是否毕业——根本没有现成字段可用。这时候就该自定义msg了。自定义msg其实就是给topic设计专属的数据结构模板，相当于你自己定义一张“数据表”，发布端往里面填数据，订阅端按同样的结构拆数据。这篇文章我会从一个空功能包开始，把自定义msg从定义、编译、发布、订阅到验证的整个过程完整走一遍，并给出C++和Python两套可直接使用的收发代码。适合刚学完ROS基础、想把多个字段组合成一个topic数据的人，也适合被CMake里各种依赖报错折磨过的新手。

1. 为什么要自定义msg：标准消息解决不了的通信场景

1.1 自定义msg在ROS里真正扮演什么角色

第一次接触自定义msg时，很多人以为它是某个运行库在处理消息时临时拼出来的协议对象，其实不准确。msg更像一个编译期的数据模板，catkin构建时会根据.msg文件生成对应语言的代码——C++会生成一个类，Python会生成一个模块，类的字段就和你写的字段一一对应。发布端创建这个类的实例、给字段赋值、调用publish；订阅端收到的是同一个消息类型的实例，直接读字段就行。

底层依赖的是ROS固定的序列化规则，打包和解包完全按定义顺序来，所以收发两端必须保证消息类型一致，字段顺序、字段类型都不能有偏差。这有点像快递群里约好的订单模板：姓名、电话、地址按固定顺序填写。寄件人按姓名、电话、地址填，收件人却按地址、电话、姓名读，那单子就废了。自定义msg的逻辑是一样的，只是ROS把模板定义、代码生成、序列化打包全部自动化了，你要做的就是保证“模板”一致。

1.2 标准消息的局限：Twist表达不了业务数据

标准消息之所以“标准”，是因为它覆盖了机器人领域最常见的基础概念，比如速度、位姿、里程计。但真实业务的数据结构千差万别，拿geometry_msgs/Twist来说，它只有linear和angular两组float64向量，适合描述底盘速度指令。可如果你的上层要上报一个检测结果，包含目标ID（int32）、置信度（float64）、标签名称（string）、检测时间（time），Twist一个都表达不了。

那有人会想：我拆成几个topic发呗？这个方案表面可行，实际很痛苦。多topic意味着下游要多订阅几个通道，还要自己做时间对齐。消息到达顺序稍有抖动，就会出现“A到了、B还没到”的窗口，下游要么缓存等待，要么直接丢弃，业务代码里全是这类同步补偿逻辑，越写越复杂。自定义msg把相关字段捆在一个结构体里，一次发布、一次接收、所有字段同时到达，数据一致性由消息本身保证，逻辑会简洁得多。

1.3 典型应用场景

自定义msg最常出现在这几类场景：

• 传感器融合：把雷达、摄像头、IMU多种来源的关键结果合成一个结构体上报。
• 指令附带元数据：底层速度指令之外，附带优先级、下发时间、来源标记。
• 结构化状态上报：设备的温度、电压、工作模式、报警码组合成一个消息。
• 批量数据的集合：一帧图像里的多个检测框，用一个带数组字段的消息装下。

我在项目里判断是否要自定义msg时有个朴素标准：两个字段是否必须“同生共死”。如果A字段和B字段总是需要被一起读取，它们就应该放进同一个msg里。有时候自己懒得多写一个msg，结果下游解析代码比多定义一个msg难写十倍，这笔账其实很容易算。

2. msg文件的设计与编写：从数据结构定义说起

2.1 目录和命名规范不能错

自定义msg的第一步是新建目录和文件。在功能包下面建立一个固定叫msg的目录，注意不是messages，也不是custom_msg。目录下的每个.msg文件对应一个消息类型，类型名的完整写法是“包名/文件名”。比如包名是custom_msg_example，消息文件是StudentMsg.msg，那么完整类型名就是custom_msg_example/StudentMsg，发布订阅代码里都要用这个全称。

命名上有两条约定俗成的规则：.msg文件名推荐首字母大写，这样生成出来的类名比较自然；字段名推荐用蛇形命名（lowercase_with_underscores），和ROS社区代码风格保持一致。一个包可以同时定义多个.msg文件，编译时一并处理，但一个文件只定义一个消息类型，别试图在一个文件里用分隔符塞两个结构。

2.2 字段类型怎么选

ROS1的msg支持的基础类型如下：

数组类型直接在类型后面加中括号：float64[]是变长数组，float64[3]是定长三位数组，业务数据一般优先用变长数组，扩展性更好。time类型在C++里对应ros::Time，在Python里对应rospy.Time；duration同理。

这里要提醒一句历史遗留问题：老代码里偶尔能看到byte和char两个别名，byte等价于int8，char等价于uint8。新写的msg不要用这两个别名，直接写int8/uint8更清晰，也避免不同版本ROS对它们的解释不一致。

2.3 一个完整的示例定义

我用一个学生成绩上报的消息当例子，简单且能涵盖几种常见字段。在msg目录下创建StudentMsg.msg：

# 学生信息消息 string name uint32 student_id float64 score bool is_graduated int32 semester std_msgs/Header header

解释几个选型判断。学号用uint32，是因为学号业务上不会为负，无符号类型语义更贴近；成绩用float64而不用float32，一是ROS中浮点消息默认精度更高，二是在C++侧和double直接对应，省去精度转换；header放在最后，是因为Header通常作为“安全带”存在，业务字段放前面，代码阅读时第一眼看到的是核心数据。

文件内部不写包名，完整类型名在代码里通过包名加文件名构造。字段之间的顺序是有意义的，收发两端按同样的顺序解析，所以定义成型后尽量不要改既有字段顺序，新增字段也最好追加在末尾，后面章节会再展开。

2.4 要不要加Header，时间戳怎么管

这是设计msg时常被忽略的问题。std_msgs/Header里有三个字段：seq序列号、stamp时间戳、frame_id坐标帧。如果你的消息将来要做bag回放、多传感器时间同步、TF坐标变换，Header几乎是必需品，时间戳统一从stamp里取，不需要你在业务字段里自己塞一个float64的时间值。

我的习惯是：传感器类、状态类、检测类消息一律加Header；纯命令类、业务逻辑内部消息才考虑省略。加Header的代价很小，只是定义里多写一行std_msgs/Header header，但它会把依赖项std_msgs带进来，这也是下一章重点要讲的编译配置问题。

3. CMakeLists.txt与package.xml：自定义消息编译的三大易错点

3.1 find_package里漏掉message_generation：八成新手的第一次报错

CMakeLists.txt中最容易翻车的第一个位置是find_package。假设包名custom_msg_example，标准写法如下：

find_package(catkin REQUIRED COMPONENTS roscpp rospy std_msgs message_generation )

message_generation是专门生成消息代码的组件，必须写。如果只写了roscpp、rospy、std_msgs，运行catkin_make时大概率会看到类似“Could not find the required component message_generation”的报错。这是自定义msg最常见的编译错误，我见过太多人卡在这一步，基本都是find_package里少了这一项。

为什么既要std_msgs又要message_generation？因为StudentMsg.msg里用了std_msgs/Header，你的.msg文件相当于“include”了另一个包的消息类型，构建时就必须显式依赖那个包。message_generation负责把整个文件内容变成可调用的C++/Python类。

3.2 add_message_files和generate_messages的依赖逻辑

继续看CMakeLists的关键段落：

add_message_files( FILES StudentMsg.msg ) generate_messages( DEPENDENCIES std_msgs )

add_message_files把需要编译的.msg文件列进去，generate_messages负责生成代码。DEPENDENCIES清单里写的，是“当前定义的msg里用到的其他消息包”。如果仅仅定义原生类型字段，比如int32和float64的组合，DEPENDENCIES甚至可以不写；但只要用了std_msgs/Header，DEPENDENCIES里就必须有std_msgs。

这一步漏掉的话，有时候编译能过，但生成的Python模块里可能缺少Header依赖，运行import时报错，非常隐蔽。还有一种情况：你的消息使用了另一个自定义包的消息类型，DEPENDENCIES需要写那个包名，否则编译顺序排不对，下游拿到的接口可能不完整。

3.3 catkin_package里的message_runtime：运行依赖的隐性坑

包配置的另一半是catkin_package这一段：

catkin_package( CATKIN_DEPENDS roscpp rospy std_msgs message_runtime )

message_runtime是消息运行依赖。如果只想着“编译时能用”而忘记写它，定义消息的包本身可能能编过，可一旦其他包引用了你的自定义消息，catkin在解析运行依赖时就会缺项，轻则警告，重则rosrun阶段报找不到消息类型。这个问题的诡异之处在于：本节点一切正常，错误却出现在别处的依赖链上，排查起来很费劲。

所以我的习惯是，只要包里定义了msg，无论情况如何都把message_runtime加上，不给自己留运行期隐患。它是那种“写了感觉没用、漏了可能出事”的字段，稳妥比聪明更重要。

3.4 package.xml也要保持同样的依赖声明

打开package.xml，需要增加的依赖项如下：

<buildtool_depend>catkin</buildtool_depend> <build_depend>message_generation</build_depend> <build_depend>std_msgs</build_depend> <build_depend>roscpp</build_depend> <build_depend>rospy</build_depend> <exec_depend>message_runtime</exec_depend> <exec_depend>std_msgs</exec_depend> <exec_depend>roscpp</exec_depend> <exec_depend>rospy</exec_depend>

注意ROS版本差异：老版本里用run_depend，现代Noetic用exec_depend。如果跟随网上教程抄了老语法，在Noetic下catkin会给出提示。build_depend和exec_depend分别对应编译期和运行期，message_generation只需要编译期，message_runtime则需要运行期，两者不能互相替代。CMake列表和XML两侧的依赖保持一致，是避免各种随机报错的基础。

3.5 为什么catkin对依赖声明这么敏感

这个包配置环节为什么这么容易把人卡住？因为catkin的构建系统是声明式的，所有跨包依赖都是通过build_depend、find_package这些声明排出来的构建图。你在.msg里引入std_msgs/Header，本质上是引入一个接口依赖；你生成消息代码，本质上是把一个接口定义变成可调用的类。任何一个环节声明缺失，构建图就对不完整，于是错误总是在最意想不到的地方冒出来。

所以排查CMakeLists问题时，不要只盯着当前这一行看，要顺着“我的.msg里到底引用了谁”这个思路走一遍。分成三个问题：编译消息需要哪些组件，消息内容依赖哪些包，运行时需要哪些包。这三个问题回答完了，CMakeLists和package.xml基本就不会错。

4. 发布端与接收端完整实现：C++与Python双版本可抄作业

4.1 C++发布节点的完整写法

在src目录下新建student_info_publisher.cpp：

#include "ros/ros.h" #include "custom_msg_example/StudentMsg.h" int main(int argc, char** argv) { ros::init(argc, argv, "student_info_publisher"); ros::NodeHandle nh; ros::Publisher pub = nh.advertise<custom_msg_example::StudentMsg>("student_info", 10); ros::Rate rate(1); while (ros::ok()) { custom_msg_example::StudentMsg msg; msg.header.stamp = ros::Time::now(); msg.name = "demo_student"; msg.student_id = 2024001; msg.score = 95.5; msg.is_graduated = false; msg.semester = 1; pub.publish(msg); rate.sleep(); } return 0; }

头文件路径为什么是custom_msg_example/StudentMsg.h？因为catkin生成的头文件放在devel/include/<包名>/<消息名>.h，编译时源文件按这个路径include，CMake那边会自动把头文件搜索路径加好。advertise模板参数写清楚消息类型，话题名student_info只是一个字符串标识，与消息类型本身完全独立，两边的“名字+类型”都能匹配，通信就能建立。

msg.header.stamp在这里用ros::Time::now()赋值。如果不给Header赋值，时间戳默认是0，后面做时间同步或bag回放时会非常痛苦。频率用ros::Rate(1)控制成1Hz，方便观察数据流动，实际项目里按业务需求调整。

4.2 C++订阅节点的处理方式

在src目录下新建student_info_subscriber.cpp：

#include "ros/ros.h" #include "custom_msg_example/StudentMsg.h" void infoCallback(const custom_msg_example::StudentMsg::ConstPtr& msg) { ROS_INFO("name: %s, id: %u, score: %.2f, graduated: %d, semester: %d", msg->name.c_str(), msg->student_id, msg->score, msg->is_graduated, msg->semester); } int main(int argc, char** argv) { ros::init(argc, argv, "student_info_subscriber"); ros::NodeHandle nh; ros::Subscriber sub = nh.subscribe("student_info", 10, infoCallback); ros::spin(); return 0; }

回调函数接收的是消息类型的ConstPtr，本质上是共享指针，所以内部用msg->字段来访问。这里有个小经验：ROS_INFO的格式化字符串处理string类型时，需要调用c_str()，printf家族不支持直接输出std::string；id字段是uint32，格式化要用%u而不是%d，我之前见过有人用%d打印大数变负数，排查了半天才找到是格式化符号的问题。

ros::spin()进入回调等待状态，发布端每发一帧，这个函数就会触发一次infoCallback。如果你在回调里做耗时操作，会阻塞后续消息的到达，所以不要在回调里放重活，保持回调短小，这是ROS编程的基本素养。

4.3 CMake的编译目标配置

C++可执行文件需要在CMakeLists里显式声明：

add_executable(student_info_publisher src/student_info_publisher.cpp) add_dependencies(student_info_publisher ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS}) target_link_libraries(student_info_publisher ${catkin_LIBRARIES}) add_executable(student_info_subscriber src/student_info_subscriber.cpp) add_dependencies(student_info_subscriber ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS}) target_link_libraries(student_info_subscriber ${catkin_LIBRARIES})

为什么要格外强调add_dependencies这一行？因为catkin_make会先生成消息代码，再编译你的可执行文件，有了这行依赖声明，构建系统才能保证“头文件已经生成，然后才开始编译当前源文件”。不写它，第一次编译经常报找不到StudentMsg.h，第二次再编译又好了，这种偶发性报错最消耗耐心。写上去之后，构建顺序就稳了。

Python的发布和订阅脚本不需要在CMakeLists里注册，只要放在包目录下并且赋予执行权限，rosrun就能直接运行。很多新手习惯在Windows下编辑脚本，传到Linux上忘了chmod +x，rosrun提示找不到文件，检查时总觉得文件明明存在——第一反应就该看执行权限。

4.4 Python版本发布与订阅的代码

在包内新建scripts目录，放入student_info_publisher.py：

#!/usr/bin/env python3 import rospy from custom_msg_example.msg import StudentMsg rospy.init_node("student_info_publisher") pub = rospy.Publisher("student_info", StudentMsg, queue_size=10) rate = rospy.Rate(1) while not rospy.is_shutdown(): msg = StudentMsg() msg.header.stamp = rospy.Time.now() msg.name = "demo_student" msg.student_id = 2024001 msg.score = 95.5 msg.is_graduated = False msg.semester = 1 pub.publish(msg) rate.sleep()

import语句是最容易出错的地方：from custom_msg_example.msg import StudentMsg，注意是“包名.msg”这个模块路径，不是custom_msg_example_msg，也不是直接from StudentMsg import。生成器会根据StudentMsg.msg自动生成StudentMsg类，类名与文件名一致。如果import时报ModuleNotFoundError，优先检查是否source了devel/setup.bash，以及Python版本是否和编译环境匹配。

订阅端student_info_subscriber.py：

#!/usr/bin/env python3 import rospy from custom_msg_example.msg import StudentMsg def info_callback(msg): rospy.loginfo("name: %s, id: %d, score: %.2f, graduated: %s, semester: %d", msg.name, msg.student_id, msg.score, msg.is_graduated, msg.semester) rospy.init_node("student_info_subscriber") rospy.Subscriber("student_info", StudentMsg, info_callback) rospy.spin()

写完脚本后执行chmod +x，给两个脚本都加上执行权限。Python是动态语言，回调函数里msg的字段直接访问即可，不需要像C++那样处理指针和解引用。

4.5 发布和订阅要不要写进同一个节点

很多新手会问：能不能在一个节点里既发布又订阅？当然可以，循环里同时pub和调用spin就能跑通，但那只适合单节点自测。我更建议发布和订阅分开写，理由不只是代码模块化，更重要的是可以跨语言验证自定义msg的正确性。

比如你用C++发布、用Python订阅，如果数据照样能正确解析，说明你的消息定义本身没有问题，和语言无关。自定义msg的底层序列化是语言无关的，这一步跨语言互认的测试非常值得做，它能证明你的消息结构是真正可用的。

5. 编译与运行验证：从catkin_make到rostopic工具链

5.1 编译流程与生成物位置

回到工作空间根目录，执行：

catkin_make source devel/setup.bash

编译成功后，自定义消息会生成两类关键产物：C++头文件放在devel/include/custom_msg_example/StudentMsg.h，Python模块放在devel/lib/python3/dist-packages/custom_msg_example/msg/StudentMsg.py。如果使用老版本ROS配了python2，路径会对应地变成python2.7/dist-packages。

source setup.bash的核心作用之一，就是把这些路径注入CPATH和PYTHONPATH。很多人Python里import不到生成的msg，第一反应怀疑代码写错，实际九成情况是没在同一终端source环境，或者编译根本没成功。每次打开新终端，都要记得source一遍。

5.2 用rosmsg验证消息定义

编译完成后，先别急着跑节点，用rosmsg验证一下消息结构：

rosmsg show custom_msg_example/StudentMsg

输出类似下面这样：

string name uint32 student_id float64 score bool is_graduated int32 semester std_msgs/Header header

如果你再结合rosmsg show std_msgs/Header，就会看到seq、stamp、frame_id三个字段。看到Header展开后的三个嵌套字段，说明你的消息定义和std_msgs的依赖都解析成功了，生成的代码是完整的。这个步骤虽然简单，但能提前暴露编译生成是否完整。

5.3 用rostopic验证收发链路

开两个终端，一个运行发布端，一个运行订阅端：

rosrun custom_msg_example student_info_publisher rosrun custom_msg_example student_info_subscriber

订阅端应每1秒打印一次学生信息。此时开第三个终端，用rostopic命令查看通讯状态：

rostopic list | grep student_info rostopic type /student_info rostopic echo /student_info rostopic info /student_info

rostopic type应该输出custom_msg_example/StudentMsg；rostopic echo会把每一帧消息完整打印出来；rostopic info里的Publisher count和Subscriber count都应该是1。这套命令是排查topic问题的基本功——比如消息没收到，先看echo有没有数据，再看type是否一致，九成问题都能定位。

5.4 其他包如何复用你的自定义消息

自定义消息最大的价值在于跨包复用。假设另一个包other_package要收发StudentMsg，它需要做三件事：

• 在package.xml里添加对custom_msg_example的build_depend和exec_depend。
• 在CMakeLists里find_package(catkin REQUIRED COMPONENTS custom_msg_example)。
• 代码里正常include或者import自定义消息类型。

如果other_package自己也定义了新msg，并且在新msg里引用了custom_msg_example/StudentMsg，那它自己的generate_messages里必须写DEPENDENCIES custom_msg_example。这几乎和本包内部依赖std_msgs是一个道理，只是把依赖从系统包换成自定义包。这个环节是工程化里最容易卡住的地方，特别是多个包互相引用消息时，依赖顺序只要错一个，整棵构建树就排不出来。

6. 坑位盘点与消息结构设计建议：别把收发做成了“一次性代码”

6.1 高频报错与排查对照表

把前面分散的排错经验汇总成一张表，方便你遇到问题时快速对照。

6.2 编译通过但收不到数据的排查顺序

如果发布者和订阅者都起来了，但订阅者没有输出，我的排查顺序固定是这几步：

1. 先rostopic list，看话题名是否存在，和代码里subscribe的名字是否一致。
2. 再rostopic echo，看话题上有没有数据在流动。
3. 用rostopic info看发布订阅计数。
4. 最后对比两端消息类型是否完全一致。

有个容易忽略的场景：发布端是单次发布，没有保持循环发布，订阅者上线晚了几秒，所有数据都错过了。这时候要么把发布端改成持续循环，要么使用latched话题让新订阅者能立刻收到最近一帧。我之前写一次性测试脚本时常常犯这个错，后来干脆把发布频率提高到10Hz，问题立刻消失。

6.3 消息字段设计：现在就为将来留余地

自定义msg看着简单，但改起来比新建一个麻烦得多，因为消息可能已经被多个节点的依赖链锁定了。这些年我沉淀下来的几个习惯：

• 传感器类消息一律加Header。统一时间基准很重要，现在用不上，后面bag回放、时间同步、坐标变换全都要。
• 字段顺序固定后不要乱动。后续升级时尽量只在尾部新增字段，不要改已有字段名和类型，因为序列化按定义顺序解析，尾部新增对旧代码兼容性最好。
• 用枚举值代替裸字符串。比如状态字段用uint8定义常量，避免字符串拼写不一致导致对不上。
• 优先用变长数组。定长数组一旦定死就是协议的一部分，后期扩展只能再开新字段。
• 一个消息只负责一个业务域。不要把“学生成绩”和“房间温度”塞进同一个msg，宁可多定义几个小消息再嵌套。

6.4 收发的下一步：嵌套消息与混合语言验证

做熟基本收发后，自然会碰两个进阶场景。第一是消息嵌套：在StudentMsg.msg里放另一个自定义消息类型，比如ScoreDetail数组字段，定义时依然按规则生成，只是要注意依赖链，被嵌套消息所在的包也要写进generate_messages的DEPENDENCIES。第二是跨语言互认：用C++发布、Python接收，或者反过来，看到数据能正确解析，说明消息定义已经跨越语言边界了。

这也是自定义msg最值得亲手验证的一点——ROS通信的序列化层是语言无关的，消息结构一旦定义好，C++、Python、以及后续其他工具链都能复用，这才是收发自定义消息背后的真正长远价值。