从零搭建ROS2机器人：URDF建模、RVIZ2可视化与关节驱动实践

创客营第6天早上，我站在教室门口，听见两个学员在争：用键盘能不能让小乌龟走出五角星。这个画面其实挺触动我的——经过前5天的折腾，他们已经不把ROS2当成一套需要背命令的工具，而是当成一个"活的东西"在玩了。这正是少年创客营想要的状态。

但今天要做的不是继续玩小乌龟。今天我们从"运行别人的例程"跨到"拥有自己的机器人"：用URDF给机器人搭骨架，用RVIZ2把它显示出来，再写一个自己的节点，让话题数据驱动关节转起来。这篇内容适合三类人看：正在带青少年入门ROS2的老师、前5天刚好把环境和小乌龟跑通的学员、以及任何想从"跑通例程"迈向"自己建模"的ROS2初学者。

1. 第6天为什么是分水岭：前5天我们到底种下了什么

1.1 前5天的课程主线

少年创客营的进度不是随便排的。为了应对不同基础的学员，我的原则是"先让机器动起来，再讲透理论"，所以前5天设计的是一条非常明确的爬坡路线：

这个顺序可能和很多教材不一样。教材一般会把架构放在最前面，但给青少年讲课时，架构讲太久他们会睡着。我选择反过来：先让他们用命令行遥控小乌龟，让小乌龟真的按方向键动起来，他们才会对"节点在通信"这件事产生体感，然后再回过头讲概念。

到第5天结束时，绝大部分学员已经完成了一个关键转变：能在自己的ros2_ws工作空间里创建一个包，编译通过，并且跑起来一个自己写的发布者节点。虽然他们写的节点干的事情很简单，只是不断发一句话，但"写代码→编译→运行→被另一个程序收到"这个闭环一旦打通，后面所有内容都是在往这个闭环里加东西。

1.2 Day 6 要解决的问题

前5天有个隐藏问题一直没被正面处理：学员玩的小乌龟也好，自己写的 talker 也好，都是"别人定义好的东西"。小乌龟长得那样，是因为乌龟包早就写死了；talker 发的消息也只是普通字符串，看不见摸不着。

第6天要解决的核心问题就是：我们能不能从零拥有一个自己的机器人？这个机器人不需要是真的硬件，先在软件里把"长什么样""关节怎么动""谁去控制它"这三件事完整走一遍。走完这一步，以后再碰真实机器人的电机、轮子、传感器，思路完全一样。

所以我把 Day 6 的目标拆成三条：

1. 用 URDF 给机器人建模：底盘是蓝色的、轮子是深色的、关节在哪、轮子绕哪个轴转。
2. 用 RVIZ2 把这个模型可视化出来，并且能拖拽视角观察。
3. 写一个自己的节点，发布 joint_states 话题，驱动机器人的轮子转动。

听起来很多，但做起来是顺的，因为第5天的发布者节点已经帮学员攒下了"如何发布一个话题"的肌肉记忆，今天只是把话题内容从字符串换成关节状态数据。

1.3 Day 6 的成品预览

我在开营时给学员看了一段录好的效果视频：一个蓝色底盘、两个深色轮子的小车静止在 RVIZ2 画面中央，然后在某个瞬间，两个轮子开始均匀转动，身边终端里滚动着一行行日志。

有学员问："老师，它为什么不动？" 我说："因为控制它转圈的节点还没有运行。" 等wheel_spinner一启动，轮子就转了。那一刻所有人都看明白了——机器人模型本身是"死"的，是话题里的数据让它"活"起来的。这就是机器人开发最核心的心智模型。

这个成品预览非常重要。对于少年学员，你给一串目标清单，他记不住；你给他一个"做完之后我能看到什么"的画面，他就能自己惦记着往那个方向走。

2. 把话题讲成厨房传菜：30分钟吃透ROS2通信的核心

2.1 节点、话题、消息：厨房里的三个角色

少年创客营里第一个难点就是话题通信。我发现如果直接讲"发布者/订阅者模型"，学员容易陷入术语迷宫。后来我换了厨房的例子，效果好了很多。

节点可以理解成厨房里各司其职的厨师：一个负责切菜，一个负责炒菜，一个负责装盘。每个厨师只关心自己的活，切菜的不需要知道炒菜的怎么颠勺。

话题是厨房里的传菜通道，比如一条传送带。切菜师傅把切好的菜放上传送带，炒菜师傅从传送带上拿菜。关键在于，传送带本身不关心谁放菜、谁拿菜，它只负责把东西从一头送到另一头。

消息就是传送带上传递的"一盘菜"，它必须服从一个固定的规格：比如装菜的盘子必须是统一的尺寸，如果某天换了个超大号盘子，传送带就可能卡住。在 ROS2 里，这条"统一规格"就是消息类型。

这个类比能解释很多后续会踩的坑：为什么发布者和订阅者的消息类型必须一致？因为你的菜是装盘子里传的，人家传送带只认这种盘子。为什么话题名拼错一个字就收不到？因为传送带编号搞错了，菜送到别的通道去了。

2.2 命令行三件套：先动手，概念自然就通了

讲完类比，我的习惯是立刻让学员回到终端，用小乌龟亲手感受"数据在流动"。

第一步，开一个终端，启动小乌龟仿真器：

ros2 run turtlesim turtlesim_node

第二步，再开一个终端，启动键盘遥控节点：

ros2 run turtlesim turtle_teleop_key

这时候按方向键，小乌龟已经在动了。但我让学员先别急着玩，而是开第三个终端，依次敲三组命令：

ros2 node list ros2 topic list ros2 topic echo /turtle1/cmd_vel

ros2 node list会列出当前所有节点，你能看到/teleop_turtle和/turtlesim。ros2 topic list会列出话题，比如/turtle1/cmd_vel和/turtle1/pose。

最有意思的是ros2 topic echo /turtle1/cmd_vel。执行这条命令后回到键盘窗口按方向键，echo 窗口里会不断刷出速度数据：

linear: x: 2.0 y: 0.0 z: 0.0 angular: x: 0.0 y: 0.0 z: 0.0 ---

这时候学员的表情一般是恍然：原来我按了一下方向键，背后真的有一条数据流从这个节点发到那个节点。消息不是虚拟的，是真实存在、可以被"偷看"到的。这比任何PPT都管用。

2.3 用 rqt_graph 验证"看不见的管道"

如果时间允许，我还会让学员跑一下可视化工具 rqt_graph：

rqt_graph

屏幕上会出现两个椭圆，一个写着/teleop_turtle，一个写着/turtlesim，中间有一条连线，连线上标着/turtle1/cmd_vel。这条线就是"话题管道"的图形化表达。

我会抛一个关键问题："如果你先开 rqt_graph，再开 teleop 节点，图会变吗？" 答案当然会。ROS2 话题是动态的，节点上线后话题才出现，节点下线后话题就消失。这个特性对后面排查问题特别重要——很多"RVIZ2里看不到模型"的怪问题，根源就是某个节点没启动，话题根本不存在。

第2天到第3天，我们会反复用这三件套：ros2 node list、ros2 topic list、ros2 topic echo。到了第6天，学员已经能条件反射地用它来排查问题了，这比记住任何架构图都实在。

3. 写第一个发布者节点：让数据在终端里清清楚楚

3.1 创建功能包：命令背后做了什么

在给 URDF 模型写关节驱动之前，我会带学员先写一个更简单的发布者节点。这个节点发布普通的字符串消息，目的是复习第5天的知识点，同时为后面的joint_states发布者热身。

首先，确保你在工作空间的 src 目录里：

cd ~/ros2_ws/src ros2 pkg create --build-type ament_python day6_publisher --dependencies rclpy std_msgs

这条命令里，--build-type ament_python表示创建一个 Python 包；--dependencies rclpy std_msgs表示自动把依赖写进package.xml。依赖很关键，后面如果我们用了sensor_msgs，也要手动加。

关于这个命令，我发现很多学员会忽略--dependencies的作用。如果不加，编译不会报错，但运行时 import 会失败，因为包的依赖信息在 package.xml 和 setup.py 里是缺的。所以每次创建包之前，先想清楚：我这个包要用什么消息类型？都列在依赖里。

3.2 talker.py：一个最小可用的发布者

创建完成后，进入包的 Python 源码目录：

cd ~/ros2_ws/src/day6_publisher/day6_publisher

新建一个talker.py，写入下面的代码：

import rclpy from rclpy.node import Node from std_msgs.msg import String class Talker(Node): def __init__(self): super().__init__('day6_talker') self.publisher_ = self.create_publisher(String, 'chatter', 10) self.timer = self.create_timer(0.5, self.timer_callback) self.count = 0 def timer_callback(self): msg = String() msg.data = 'Hello from Day 6: %d' % self.count self.publisher_.publish(msg) self.get_logger().info('Publishing: %s' % msg.data) self.count += 1 def main(args=None): rclpy.init(args=args) node = Talker() rclpy.spin(node) node.destroy_node() rclpy.shutdown() if __name__ == '__main__': main()

这段代码非常短，但它包含了一个 ROS2 节点所有必备的零件：

• 继承Node，在构造函数里给节点取名叫day6_talker。
• 创建一个发布者：消息类型是std_msgs/String，话题名是chatter，队列长度是 10。
• 用create_timer每 0.5 秒回调一次，相当于设定一个"每隔半秒做一次这件事"的闹钟。
• 回调函数里做的事：造一个消息、填数据、发布出去、打印日志。

这里我会特意强调create_timer的作用。没有它，节点会一直在spin()里空转，什么也不干。定时器就是给节点装上了一个节拍器，这是所有周期发布型节点的标准写法。

写完代码后，还要改一下setup.py里的entry_points，否则运行ros2 run时找不到这个可执行文件：

entry_points={ 'console_scripts': [ 'talker = day6_publisher.talker:main', ], },

3.3 编译运行，并在另一个终端里"抓到"数据

回到工作空间根目录编译：

cd ~/ros2_ws colcon build --packages-select day6_publisher source install/setup.bash ros2 run day6_publisher talker

跑起来后，发布者自己的终端会不断打印：

[INFO] ... Publishing: Hello from Day 6: 0 [INFO] ... Publishing: Hello from Day 6: 1

这时候再开一个新终端，用第2天学过的 echo 去"抓"这条数据流：

source ~/ros2_ws/install/setup.bash ros2 topic echo /chatter

如果一切正常，你会看到：

data: Hello from Day 6: 12 ---

再运行ros2 topic info /chatter，能从输出里看出话题类型、发布者数量和订阅者数量。这一步我坚持让每个学员做，因为它是"通信闭环"的验收标准：我的程序真的发出了数据，另一个程序真的能收到。只有亲手跑通这个，后面发布joint_states才有底气。

3.4 为什么第6天选 Python 而不是 C++

几乎每次都有家长问：为什么不用 C++？真实机器人不是都用 C++ 吗？

我的回答是：第6天选 Python 不是因为 C++ 不好，而是不想让语言细节挡住通信概念。Python 版 ROS2 节点改完代码直接colcon build再运行，不需要处理头文件、CMakeLists、链接库这些事。对少年学员来说，C++ 的编译报错信息光读懂就要花掉半节课。

我会跟学员说清楚：Python 适合把思路跑通，等你理解了思路，未来需要更高性能时再去接触 C++ 完全来得及。机器人开发里最重要的是通信思维，不是语言本身。

4. URDF建模：用XML给机器人搭骨架

4.1 URDF的本质：连杆与关节的"说明书"

URDF 全称是 Unified Robot Description Format，翻译过来就是"统一机器人描述格式"。听起来很唬人，本质就是一个 XML 文件，用标签描述机器人由哪些部件组成、这些部件怎么连接。

我给学员的类比是：URDF 就像一份乐高拼装说明书。说明书不会直接给你一个拼好的机器人，而是告诉你：这里有一块蓝色底板，那里有一个轮子，轮子和底板之间用一根轴连接。这份说明书既不负责让机器人动起来，也不负责模拟物理世界，它只负责"描述"。

URDF 里两个最核心的标签是<link>和<joint>。<link>表示机器人的一个部件，比如底盘、轮子、机械臂的臂杆；<joint>表示部件之间的连接关系，决定两个部件相对位置怎么摆、能不能转动。

4.2 搭一个最简单的底盘

我们直接从零搭一个小车。先只做一块蓝色底板：

<robot name="day6_bot"> <link name="base_link"> <visual> <origin xyz="0 0 0.04" rpy="0 0 0"/> <geometry> <box size="0.4 0.25 0.08"/> </geometry> <material name="blue"> <color rgba="0.2 0.3 0.9 1.0"/> </material> </visual> </link> </robot>

这里每一步都是有讲究的：

• <box size="0.4 0.25 0.08"/>表示底盘是一个长方体，长 0.4 米、宽 0.25 米、厚 0.08 米。
• <origin xyz="0 0 0.04" rpy="0 0 0"/>表示这个长方体的几何中心相对base_link坐标系原点抬高 0.04 米。这样做的目的是让底盘下表面正好落在 z=0 的平面上，也就是地面。
• <color rgba="0.2 0.3 0.9 1.0"/>表示蓝色。

只加一个 link 时，RVIZ2 已经能显示这个底盘了，但它还只是"一块会悬浮的蓝色砖头"。底盘没有轮子，算不上机器人。

4.3 加上轮子：joint 是让骨架灵活的关键

接下来给底盘加两个驱动轮。轮子本身是<link>，轮子和底盘的连接关系用<joint>描述。

以左轮为例：

<joint name="left_wheel_joint" type="continuous"> <parent link="base_link"/> <child link="left_wheel"/> <origin xyz="0 0.15 0.05" rpy="0 0 0"/> <axis xyz="0 1 0"/> </joint>

三个地方需要重点解释：

type="continuous"表示这是一个可以无限旋转的关节，适合轮子。ROS2 常用的关节类型有四种：fixed（固定，不能动）、continuous（无限旋转）、revolute（有限角度转动）、prismatic（直线滑动）。我们的小车驱动轮用continuous，万向支撑轮用fixed。

<origin xyz="0 0.15 0.05"/>表示轮子中心相对底盘中心的位置：x 方向 0 表示在中点，y 方向 0.15 表示在左侧，z 方向 0.05 表示轮心离地 0.05 米。为什么要 0.05？因为轮子半径是 0.05，轮心离地 0.05，轮子下缘才正好贴地。

<axis xyz="0 1 0"/>表示关节绕 y 轴旋转。差速小车的轮子就是绕 y 轴转，转起来车才能沿 x 方向前进或后退。这里的轴写错，轮子就会在空中乱晃。

轮子 link 的视觉部分也有一点小坑。URDF 的<cylinder>默认轴线沿 z 轴，也就是圆柱是"竖着"的。但车轮要像方向盘一样横过来，所以要在 visual 的<origin>里加一个绕 x 轴旋转 90 度的角度：

<link name="left_wheel"> <visual> <origin xyz="0 0 0" rpy="1.5707963 0 0"/> <geometry> <cylinder radius="0.05" length="0.03"/> </geometry> <material name="dark"> <color rgba="0.2 0.2 0.2 1.0"/> </material> </visual> </link>

4.4 完整URDF文件与语法检查

把底盘、左右轮和一个支撑球组合起来，得到完整的day6_bot.urdf：

<?xml version="1.0"?> <robot name="day6_bot"> <link name="base_link"> <visual> <origin xyz="0 0 0.04" rpy="0 0 0"/> <geometry> <box size="0.4 0.25 0.08"/> </geometry> <material name="blue"> <color rgba="0.2 0.3 0.9 1.0"/> </material> </visual> </link> <joint name="left_wheel_joint" type="continuous"> <parent link="base_link"/> <child link="left_wheel"/> <origin xyz="0 0.15 0.05" rpy="0 0 0"/> <axis xyz="0 1 0"/> </joint> <link name="left_wheel"> <visual> <origin xyz="0 0 0" rpy="1.5707963 0 0"/> <geometry> <cylinder radius="0.05" length="0.03"/> </geometry> <material name="dark"> <color rgba="0.2 0.2 0.2 1.0"/> </material> </visual> </link> <joint name="right_wheel_joint" type="continuous"> <parent link="base_link"/> <child link="right_wheel"/> <origin xyz="0 -0.15 0.05" rpy="0 0 0"/> <axis xyz="0 1 0"/> </joint> <link name="right_wheel"> <visual> <origin xyz="0 0 0" rpy="1.5707963 0 0"/> <geometry> <cylinder radius="0.05" length="0.03"/> </geometry> <material name="dark"/> </visual> </link> <joint name="caster_joint" type="fixed"> <parent link="base_link"/> <child link="caster"/> <origin xyz="0.1 0 0.02" rpy="0 0 0"/> </joint> <link name="caster"> <visual> <origin xyz="0 0 0" rpy="0 0 0"/> <geometry> <sphere radius="0.02"/> </geometry> <material name="gray"> <color rgba="0.7 0.7 0.7 1.0"/> </material> </visual> </link> </robot>

写完后，如果安装了liburdfdom-tools，可以立刻用check_urdf检查文件有没有语法问题：

sudo apt install liburdfdom-tools check_urdf day6_bot.urdf

正常的输出会列出机器人包含哪些 link 和 joint，以及哪些 link 是 root。如果 XML 标签没闭合或者坐标引用写错，这里就会直接报出来。我建议大家每写完一个 URDF 就检查一次，别等到 RVIZ2 里一片空白才开始慌。

另外有个细节必须说明：这个 URDF 只写了<visual>，没有写<collision>和<inertial>。纯可视化阶段这是足够的，但如果未来要把模型放进 Gazebo 做物理仿真，这两个标签必须补上，否则模型没有碰撞体积，也没有质量，仿真器会把它当"幽灵"处理。

5. RVIZ2显示与关节驱动：从静态骨架到能转的轮子

5.1 用launch文件一次启动所有组件

URDF 文件写好后，要让它显示出来需要启动三个东西：

• robot_state_publisher：读取 URDF 并发布 TF 变换，RVIZ2 靠 TF 才知道每个部件在哪。
• 一个发布关节状态的节点（我们先不启动joint_state_publisher，后面解释为什么）。
• rviz2：可视化界面。

如果每次都在四个终端里手动敲命令，很容易漏启动一个。我通常在工程里放一个 launch 文件，让ros2 launch一次搞定。在day6_publisher包下新建launch目录，创建day6_display.launch.py：

import os from launch import LaunchDescription from launch_ros.actions import Node def generate_launch_description(): urdf_path = '/home/your_name/ros2_ws/src/day6_publisher/urdf/day6_bot.urdf' with open(urdf_path, 'r') as f: robot_description = f.read() return LaunchDescription([ Node( package='robot_state_publisher', executable='robot_state_publisher', parameters=[{'robot_description': robot_description}], ), Node( package='rviz2', executable='rviz2', name='rviz2', ), ])

注意把urdf_path换成你自己的绝对路径。真实工程里一般会用Command和 xacro 处理路径，但在教学场景中，直接用open(...).read()更直观，学员能一眼看明白"我们只是把 URDF 文件的文本内容传给了robot_description参数"。

要让这段代码能被包找到，还需要在setup.py里把launch目录加进data_files：

import os from glob import glob data_files=[ (os.path.join('share', package_name, 'launch'), glob('launch/*.launch.py')), ],

接下来编译并启动：

cd ~/ros2_ws colcon build --packages-select day6_publisher source install/setup.bash ros2 launch day6_publisher day6_display.launch.py

RVIZ2 窗口会弹出来，但模型通常不会立刻出现，还需要做两项设置。

5.2 RVIZ2里的三步设置：Fixed Frame、RobotModel、观察

第一次打开 RVIZ2，界面里只有一个黑色的 3D 空间，没有小车。这不是出错，而是 RVIZ2 不知道你想看什么。你需要三步：

第一步，在左上角Global Options里把Fixed Frame改成base_link。Fixed Frame 是 RVIZ2 里所有坐标的基准，必须设成 URDF 里真实存在的 link 名。如果这里填错了，或者填了一个不存在的 link，画面里往往什么都显示不出来。

第二步，点击左下角Add按钮，弹出的对话框里选RobotModel。添加后，左侧面板会出现一个RobotModel条目，它的Description Topic默认就是/robot_description，正好对应robot_state_publisher发布的那个话题。

第三步，把视角调整到合适位置。按住鼠标中键拖动旋转，滚轮缩放，Ctrl加鼠标左键平移。对新手来说，把视角调到斜上方 45 度看小车最舒服。

这时候，蓝色底盘、两个深色轮子、灰色的支撑球应该都显示出来了。但轮子还是静止的，因为还没有任何节点给关节发布位置数据。

5.3 亲手发布joint_states：轮子真正转起来

要让轮子转，需要向/joint_states话题发布sensor_msgs/msg/JointState消息。这条消息包含三个关键字段：name（关节名列表）、position（每个关节当前角度）、velocity（每个关节速度）。

我给学员写了一个简单的轮子驱动节点，放在day6_publisher/day6_publisher/wheel_spinner.py：

import math import rclpy from rclpy.node import Node from sensor_msgs.msg import JointState class WheelSpinner(Node): def __init__(self): super().__init__('wheel_spinner') self.publisher_ = self.create_publisher(JointState, 'joint_states', 10) self.timer = self.create_timer(0.02, self.timer_callback) self.angle = 0.0 def timer_callback(self): msg = JointState() msg.header.stamp = self.get_clock().now().to_msg() msg.name = ['left_wheel_joint', 'right_wheel_joint'] self.angle += 0.02 self.angle %= (2 * math.pi) msg.position = [self.angle, self.angle] self.publisher_.publish(msg) def main(args=None): rclpy.init(args=args) node = WheelSpinner() rclpy.spin(node) node.destroy_node() rclpy.shutdown() if __name__ == '__main__': main()

代码核心就两件事：

• 每条消息里把两个关节的名字告诉系统：left_wheel_joint和right_wheel_joint。这两个名字必须和 URDF 里写的一模一样，哪怕差一个下划线，robot_state_publisher也认不出来。
• 每条消息里给这两个关节设置相同的角度值。角度值每隔 0.02 秒增加 0.02 弧度，相当于轮子每秒转 1 弧度，肉眼能看到明显转动，但又不会快到看不清。

在setup.py的entry_points里加上：

'wheel_spinner = day6_publisher.wheel_spinner:main',

然后重新编译，开一个新终端运行：

source ~/ros2_ws/install/setup.bash ros2 run day6_publisher wheel_spinner

回到 RVIZ2 窗口，你会看到两个轮子开始转动。整个过程没有一行物理仿真代码，只是往/joint_states里发角度数据，TF 系统就会自动把轮子的旋转关系算出来。这就是 ROS2 里"数据驱动可视化"最典型的演示。

我会特意让学员对比一下：talker.py发布字符串，wheel_spinner.py发布数组，这两个节点结构几乎一样——都是创建发布者、创建定时器、在回调里填充消息并发布。一旦理解了这个套路，以后控制真实电机、发导航目标、读取传感器，全是在重复这个模式。

5.4 一个常见的"多发布者冲突"现象

很多教程会在这一步让你安装并运行joint_state_publisher_gui，它会弹出一个滑条窗口，可以手动拖动关节角度：

sudo apt install ros-${ROS_DISTRO}-joint-state-publisher-gui ros2 run joint_state_publisher_gui joint_state_publisher_gui

这个工具对调试 URDF 非常有用，尤其适合检查你的关节定义是否正确。但我故意没有把它加进 launch 文件，因为有个坑：joint_state_publisher_gui和我们的wheel_spinner都在发布/joint_states。话题是允许多个发布者的，但两个发布者各发各的角度值，robot_state_publisher会"听到"两套指令，轮子就会抖动或者卡在一个奇怪的角度。

实际现象是这样的：开着joint_state_publisher_gui时，你刚拖动滑条，轮子会跟着转到某个位置，但下一秒又被wheel_spinner的数据拉回去。看起来就像机器人在抽搐。

这不是 ROS2 的 bug，而是多个发布者同时控制同一个话题的正常表现。解决思路也简单：同一时刻只保留一个发布者。想手动调试 URDF 就用 GUI，想让轮子自动转就关掉 GUI 跑自己的节点。这也是一个很好的教学点——机器人调试时经常遇到"多个来源抢同一个话题"的问题，学会定位谁在发布、发布了什么，比背命令重要得多。

6. 创客营翻车现场盘点：5个最容易卡住学员的坑

6.1 找不到功能包：三大原因逐个查

上课时最常听到的报错就是这个：

Package 'day6_publisher' not found

我的要求是，每遇到这个报错，必须按顺序自查三件事：

第一，包到底创建在哪个目录？有人会在src/day6_publisher里再创建一次src，导致目录嵌套多了一层。用ls ~/ros2_ws/src确认包目录确实在src下一级。

第二，编译有没有真的完成？回到工作空间根目录，重新colcon build --packages-select day6_publisher，观察输出有没有红色报错。Python 包最常见的编译失败原因是setup.py缩进错误或entry_points没配对。

第三，当前终端有没有source过环境？一个终端如果是在编译之前打开的，它可能没有加载新包的路径。要么重新打开终端，要么手动执行：

source ~/ros2_ws/install/setup.bash

也可以自检一下包是否被系统识别：

ros2 pkg list | grep day6

如果这步有输出，说明包已经安装到环境里，剩下的问题是终端壳环境太旧。

6.2 RVIZ2里一片空白：多半不是URDF的问题

模型在 RVIZ2 里不显示时，学员的第一反应通常是把 URDF 翻来覆去地改。但根据我的观察，90% 的空白都不是 URDF 语法问题，而是下面几个原因之一：

• Fixed Frame没设置成base_link。这是最高频的问题。刚打开 RVIZ2 时默认的 Fixed Frame 是map，但我们的机器人没有map这个坐标系，所以模型自然消失。
• 没添加RobotModel显示项。只改 Fixed Frame 不够，还要通过Add把RobotModel加进显示面板。
• robot_state_publisher没启动。可以直接在终端里查：

ros2 node list ros2 topic info /robot_description

如果/robot_description话题不存在，说明robot_state_publisher根本没跑起来，或者 launch 文件里传参的方式有问题。

排查顺序我建议固定为：先看节点，再看话题，最后才去怀疑 URDF。这个顺序能省下大量时间。

6.3 轮子纹丝不动：joint名字和消息类型的双重检查

wheel_spinner跑起来了，日志也正常，但 RVIZ2 的轮子就是不动。大多数情况是关节名对不上。

URDF 里写的是left_wheel_joint，代码里写成了wheel_left_joint，这个错我见过不下十次。我的建议是：在代码里打印一下你发出的关节名，再用ros2 topic echo /joint_states看实际发布的数据。哪怕只看到一条：

name: [left_wheel_joint, right_wheel_joint] position: [0.02, 0.02]

也能立刻发现名字是否匹配。

另外还要检查消息类型。ros2 topic info /joint_states必须显示sensor_msgs/msg/JointState。如果你不小心把std_msgs/Float64MultiArray发到/joint_states上，robot_state_publisher根本不会理你。

最后一个隐形问题是发布频率太低。如果定时回调间隔是 1 秒，轮子每秒只转 0.02 弧度，肉眼基本看不出来。感觉像是"没动"，实际在动。把频率提高到 50Hz 再看，立刻就有区别。

6.4 虚拟机卡顿：低配环境如何勉强撑住

少年创客营里有一半左右的学员是在虚拟机里装 ROS2 的。RVIZ2 对图形性能有一定要求，虚拟机里经常出现画面卡顿、模型刷新延迟。

如果只是慢，不是不能跑，可以试试几个应急手段：

1. 在虚拟机设置里打开"3D 加速"，显存尽量给到 128MB 以上。
2. 启动 RVIZ2 前设置软件渲染环境变量，有时能避免 OpenGL 驱动不兼容导致的崩溃：

   export LIBGL_ALWAYS_SOFTWARE=1

3. 关闭 RVIZ2 里不必要的显示项，比如 Grid 网格可以留着，但把Performance里的渲染质量调低。

这个方案只适合撑过课堂演示。如果真的要长期学 ROS2，我更推荐装双系统，虚拟机里做简单节点开发可以，跑可视化还是太勉强。

6.5 终端环境变量混乱：手工source到底该做几次

另一个反复出现的问题是：明明编译成功了，换个终端又找不到包。这是因为每个新终端都要source ~/ros2_ws/install/setup.bash，ROS2 的环境变量是跟着终端走的，不是全局的。

我会在第6天教大家一个一劳永逸的办法：把 source 命令写进~/.bashrc末尾：

echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc source ~/.bashrc

以后每个新终端打开时都会自动加载工作空间环境，再也不用担心漏敲source。

但这里也有一个反面教训：如果你有多个工作空间，不要把它们的 source 都塞进 bashrc 还叠加在一起。ROS2 工作空间环境是"后者覆盖前者"的，后 source 的路径会优先，容易造成你用到的包被旧版本遮蔽。最稳妥的做法是：bashrc 里只放你日常最常用的那个工作空间，临时在终端里手动 source 其他工作空间。

第6天课程结束时，教室里的画面一般是这样的：一半学员已经让轮子稳定转起来，正在用ros2 topic echo /joint_states盯着自己发的数据看；另一半卡在关节名对不上或者没 source 环境上，但排查思路已经比第3天清晰得多。

有个小学员问我："老师，为什么轮子转了，小车却不往前走？" 这个问题的答案很关键：RVIZ2 只是可视化工具，它只负责把关节角度画出来，不会模拟小车向前滚动。要让小车真的跑起来，需要的是 Gazebo 这类物理仿真环境，让车轮旋转、地面摩擦、底盘平移这些物理关系参与计算。到那天，我们写的joint_states就不再只是让视觉跟着转，而是真的能让机器人动起来。

这也是我坚持在第6天把话题、URDF、可视化、关节驱动串成一条线的原因。技术点本身不复杂，但对孩子们来说，"我自己从零画了一个机器人，然后写了一小段代码，它的轮子就转了"这件事带来的冲击力，远比任何知识点都深刻。