第一次把ROS2跑起来的人，记忆点往往不是代码，而是一只蓝色壳的小乌龟。它冒出来的那一瞬间，意味着你的环境变量、节点发现、图形渲染三条链路同时打通了；它不出现，说明其中至少有一条断了。ROS2（Robot Operating System 2）名字里带"操作系统"，但它既不是Windows那种系统，也不是一个可以双击打开的软件，准确说它是一套面向机器人的分布式通信中间件，外加一批现成的调试工具、可视化工具和仿真接口。它能干的事很具体：让几十个进程互相说话、让传感器数据和算法模块解耦、让同一套代码从笔记本搬到真机上只改配置不改逻辑。这篇内容写给三类人：刚装完系统准备入门的同学、从ROS1迁移过来被DDS和新命令搞晕的老手、以及手里有开发板或机械臂但不知道怎么把程序接进去的工程师。下面全部是我自己踩过一遍之后总结的顺序，有的地方会跟官方文档不太一样，但都是能跑通的路子。

1. 先把ROS2理解成一套分布式通信中间件

很多教程上来就让你敲命令，敲完能跑，但一换场景就懵。原因在于脑子里没有一张全局图。我建议在动手之前，先花二十分钟把下面这三件事想清楚，后面所有的命令你都能自己推导出来。

1.1 节点、话题、服务、动作这四件事各自的分工

**节点（Node）**是ROS2里的最小运行单元，一个进程里可以跑一个节点，也可以跑多个。摄像头驱动是一个节点，路径规划是一个节点，手柄遥控是一个节点。节点之间互不认识，谁也不知道对方在哪台机器上，它们只认名字。

**话题（Topic）**是最常用的通信方式，特点是一对多、单向、异步。发布者只管往一个名字上丢数据，订阅者只管从这个名字上收数据，双方不握手、不等待。这种"甩出去就不管"的模式非常适合高频数据：图像、点云、里程计、关节角度。代价是发布者无法知道有没有人在听，也没有确认机制。

**服务（Service）**是请求-响应模式，一问一答，同步阻塞。适合"查一下当前电量""切换一下模式"这种偶尔发生、需要明确结果的操作。它的限制是只有一个服务端，且调用期间客户端要等。

**动作（Action）**是服务的加强版，底层由服务加话题拼出来，但它支持三件事：执行时间长、过程中持续反馈进度、中途可以取消。机械臂从A点移动到B点、机器人导航到目标点，这类"要跑好几秒甚至几十秒、还想看进度条"的任务，就该用动作。

这四种通信方式不是让你挑一个用，而是在同一个系统里混着用。我第一次做项目时把所有东西都塞进话题，结果"是否到位"这种状态判断全靠猜，后来把运动控制改成动作，代码反而短了一半。

1.2 DDS藏在最底下，换实现不用改一行代码

ROS2和ROS1最大的区别在通信层。ROS1自己写了一套基于TCP的协议，ROS2把它整个换成了 DDS（数据分发服务） 。DDS是一套工业界已经很成熟的发布订阅标准，自带自动发现、QoS策略、跨机器组网能力。

这里有个非常关键的设计：ROS2在DDS之上又包了一层抽象，叫 RMW（ROS Middleware） 。也就是说，你写的代码调用的是 rclcpp 或者 rclpy ，它们再往下调RMW接口，RMW再去调具体的DDS实现。市面上常见的DDS实现有Fast DDS、Cyclone DDS、Connext等，切换它们只需要换一个环境变量或者装一个包，你的业务代码完全不用动。

为什么要强调这一点？因为你会遇到"换台机器就通信失败""大数据量时丢包"这类问题，而这些问题的根子往往在DDS，不在你的代码。知道这一层存在，排查时才有方向。

注意：DDS的自动发现默认会向局域网广播，实验室或办公室同网段里如果有别人也在跑ROS2，双方可能会互相看到对方的话题。这不是故障，是设计如此，用DOMAIN_ID隔离掉即可，第6节会讲。

1.3 工作空间、包和四个目录的约定

ROS2的代码组织有一套固定约定，理解它比背命令重要。一个典型的工作空间长这样：

ros2_ws/
├── src/          # 你写的所有源码和功能包
├── build/        # 编译中间产物，不用管，可以删
├── install/      # 编译出来的可执行结果，source的是这里
└── log/          # 每次colcon build的日志

src 是你唯一需要手动维护的目录。 build 、 install 、 log 都是 colcon build 生成的，出问题时把它们删掉重新编译，能解决八成的玄学问题——这一点后面还会提。

工作空间下面一层是 功能包（Package） ，它才是ROS2的分发单位。一个包必须包含 package.xml 声明依赖和元信息，以及 CMakeLists.txt （C++包）或 setup.py （Python包）。

install 目录要单独说一句：编译完之后，你运行的东西来自 install 而不是 src 。所以每次 colcon build 之后必须 source install/setup.bash ，否则你改了代码重跑还是旧行为。这个坑几乎人人踩过一次。

2. 安装ROS2：版本匹配、每步动作拆解与首次自检

安装环节是新手劝退率最高的地方，但它的难点不在技术，而在"版本对不上"。搞清楚对应关系，后面就是照着敲。

2.1 系统版本和发行版的对应关系

ROS2每个发行版都绑定固定的系统版本，装错了要么依赖冲突，要么直接装不上。截至我写这篇内容时的对应关系大致是：

ROS2发行版	代号	推荐系统	维护状态
Humble	哈姆	Ubuntu 22.04	长期支持，生态最全
Iron	铁	Ubuntu 22.04	过渡版本
Jazzy	爵士	Ubuntu 24.04	较新的长期支持版本
Rolling	滚动	最新版	开发前沿，不推荐新手

如果你问我怎么选： 刚入门就选Humble或Jazzy里跟你系统匹配的那个 。Humble的资料、第三方包、教程覆盖最广，遇到问题最容易搜到答案；Jazzy更新，配合新系统体验更好，但部分第三方包还没跟上。不要为了尝鲜装Rolling，它每天都在变，今天能编译明天可能就报错。

系统版本这东西不方便随便换，所以我的建议是：先看 lsb_release -a 确认自己的系统，再倒推该装哪个发行版，而不是先定了发行版再折腾系统。

2.2 手动安装的每一步分别在做什么

官方推荐的方式是通过apt安装，整个流程拆开看只有四步，每一步都有它的目的，明白了就不会装错。

第一步，让系统认识ROS2的软件源。 系统默认的软件仓库里没有ROS2，需要额外添加一个源地址和它的签名密钥。密钥的作用是验证下载的包确实来自官方，没被篡改。这一步最容易出问题的是网络访问慢，表现是 apt update 卡住或者报超时。如果你的网络到官方源速度不理想，可以按社区文档把源地址替换成地理位置更近的镜像，这是完全常规的操作。

第二步，安装基础包。 最常用的是 ros-<发行版>-desktop ，它包含了核心库、命令行工具、RViz2、示例程序、demo节点。如果你的机器不打算接显示器，只做后台计算，装 ros-<发行版>-ros-base 就够了，体积小很多。想省事就直接desktop，多出来的几十兆换来的是少折腾半天。

第三步，配置环境变量。 安装程序会把ROS2的命令和库放在 /opt/ros/<发行版>/ 下面，系统默认不知道这些路径，所以要source它的安装脚本。这一步是 每次打开终端都要做 的，所以通常会把这一行追加到 ~/.bashrc 末尾：

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

第四步，验证。 敲 ros2 --help ，能打印出命令列表就说明装好了。

我个人踩过的坑是： .bashrc 里同时出现了两行不同发行版的source，比如上面source了Humble，下面又source了Foxy。这种情况下最终生效的是 最后一个 ，于是你会遇到"明明装的是Humble，某个包却找不到"的诡异现象。装新版本之前，先把旧的那行注释掉。

2.3 一键脚本替你做了哪些动作，以及它的边界

社区里有维护得不错的一键安装脚本，很多人用一条命令就搞定了。省事是真的省事，但我建议至少知道它背地里做了什么，否则出问题时你连从哪查都不知道。这类脚本通常做这几件事：

• 检测当前系统版本和架构，判断该装哪个ROS2发行版，不匹配就直接退出并提示
• 替换软件源为就近镜像，配置签名密钥
• 安装desktop全套依赖，顺带处理一些常见的依赖缺失
• 把环境变量写入 ~/.bashrc ，并且检查有没有重复行
• 装一些常用的辅助工具，比如编译工具、Python包管理工具
• 最后帮你建一个工作空间，跑一个最简demo验证

它的 边界 也要清楚：脚本只负责把标准环境装好，它不会替你解决显卡驱动、硬件串口权限、DDS网络配置这些跟具体机器强相关的问题。我遇到过有人在容器里跑一键脚本，装完发现图形界面起不来，这不是脚本的问题，是容器本身没配显示转发。

提示：如果脚本执行到一半失败，不要直接重跑。先看它停在哪一步，把那一半的状态清干净（比如 apt --fix-broken install 修一下依赖），再重来。半途重跑最容易把源配置搞成两份矛盾的。

2.4 装完之后的三个自检动作

装完别急着写代码，先做三个验证，能省掉后面两小时的困惑。

第一，确认环境变量生效。 echo $ROS_DISTRO 应该输出你的发行版名字。如果没有输出，说明 .bashrc 没生效或者内容有误。

第二，跑官方示例。 打开两个终端，第一个敲：

ros2 run demo_nodes_cpp talker

第二个敲：

ros2 run demo_nodes_py listener

看到一边在数数、另一边在打印收到同样的数字，说明节点发现、话题通信、跨语言互通全部正常。

第三，跑小乌龟。 再开两个终端，分别启动界面和控制：

ros2 run turtlesim turtlesim_node
ros2 run turtlesim turtle_teleop_key

焦点放在第二个终端上，按方向键，小乌龟动了就成了。这一步同时验证了图形界面、消息收发和键盘事件输入。

如果小乌龟窗口是黑的或者直接闪退，八成是显示相关的问题，跟ROS2本身无关，先排查你的显示环境。

3. 命令行是ROS2的手：从节点到话题的调试手法

图形化工具很直观，但在机器人开发里，命令行才是主力。远程连到机器人上、没有显示器的时候，你只有命令行。而且我实测下来，很多问题的定位，用三四个命令就能收敛到原因。

3.1 run、node、topic 这三个命令的常用组合

ros2 run <包名> <可执行文件名> 是启动节点最直接的方式。它不会自动帮你管理生命周期，进程结束了就结束了。调试阶段用它最方便。

ros2 node list 列出当前所有节点。 ros2 node info /节点名 能看到这个节点发布了哪些话题、订阅了哪些话题、提供了哪些服务、有哪些动作，还能看到它用了哪些参数。

ros2 topic list -t 列出所有话题并带上类型。 这个 -t 很有用 ，因为话题名相同但消息类型不同的情况是存在的，光看名字会误判。

ros2 topic info /话题名 看这个话频有几个发布者、几个订阅者。如果发布者数量是0，说明上游节点根本没起来或者没在发。

ros2 interface show <消息类型> 查消息的具体字段结构。忘了某个字段叫什么的时候，这条命令比翻文档快。

这套组合拳的逻辑是： 先看节点有没有、再看话题有没有、再看数据有没有、最后看字段对不对 。四步下来，绝大部分"数据不通"的问题都能定位。

3.2 数据不流动时，用 hz、echo、pub 三步定位

假设你的订阅端收不到数据，按下面的顺序排查，不要跳步。

第一步，确认话题上有数据在跑。 用：

ros2 topic hz /chatter

它会持续打印这个话频的发布频率。如果一直不打印，说明根本没数据，问题在发布端。如果打印出来的频率跟预期差很远（比如你代码里写10Hz，实际只有1Hz），问题在发布端的定时器或者计算耗时。

第二步，看数据内容对不对。

ros2 topic echo /chatter

数据能打出来但订阅端还是收不到，那就不是通信问题，是订阅端的问题——可能是回调没触发、QoS不匹配（下一节讲）、或者订阅的话题名拼错了。话题名拼错这种事看着低级，但我见过太多次，包括我自己，漏一个斜杠或者大小写不一致。

第三步，手动往话题里灌数据。

ros2 topic pub /chatter std_msgs/msg/String "data: 'manual test'" -r 1

这条命令可以以固定频率往任意话题发消息，不需要写代码。它是验证下游节点的利器：如果手动发能让下游正常动作，说明下游没问题，锅在上游。

-r 1 表示1Hz， --once 表示只发一次。发消息前必须用 ros2 interface show 确认字段名， data 写成 msg 或者 Data 都不行，字段名是大小写敏感的。

3.3 服务、动作、参数在操作上的差别

这三者的命令行操作方式不一样，容易记混。我整理了一张表，平时对着看就行：

类型	列出	查看详情	触发方式
服务	ros2 service list	ros2 service type	ros2 service call
动作	ros2 action list -t	ros2 action info	ros2 action send_goal
参数	ros2 param list	ros2 param get	ros2 param set

服务调用长这样：

ros2 service call /spawn turtlesim/srv/Spawn "{x: 3.0, y: 3.0, theta: 0.0, name: 't2'}"

调用之后会阻塞等待返回，如果你等了很久没反应，说明服务端没在处理，或者服务名不对。服务调用失败时不会自动重试，也不会给友好提示，就是干等。

动作的触发多了一步，需要加 --feedback 才能看到过程反馈：

ros2 action send_goal /turtle1/rotate_absolute turtlesim/action/RotateAbsolute "{theta: 1.57}" --feedback

动作名和动作类型都要对，动作类型可以通过 ros2 action list -t 拿到。

参数是我最常用的调试手段。比如某个节点的行为不符合预期，先 ros2 param list 看它有哪些参数，再 ros2 param get /节点名 参数名 看当前值。如果节点支持动态参数，直接 ros2 param set 改一下，不用重启节点，立刻能看到效果。 不支持动态参数的节点，set会失败并报错 ，这时候只能改配置文件重启。

3.4 QoS配置不对导致的"收不到消息"

这是ROS2新手最容易被卡住、也最不容易想到的原因。前面说过底层是DDS，而DDS有一套 QoS（服务质量） 策略，发布端和订阅端的策略必须兼容，否则数据就是传不过来，而且 不会有任何报错 。

几个关键策略：

• Reliability（可靠性） ： reliable 保证每条都送到（必要时重传）， best_effort 尽力而为、允许丢。两边必须至少有一方兼容， best_effort 的发布者配 reliable 的订阅者是能通的，反过来不行。
• Durability（持久性） ： volatile 表示只发给当下在线的订阅者， transient_local 会把最后一条历史数据保留下来，后来的订阅者也能收到。
• History（历史） ： keep_last 只保留最近N条， keep_all 全保留。

默认情况下， ros2 topic pub 和大多数示例用的是 reliable ，而 传感器驱动类节点通常用 best_effort ——因为图像、点云这种高频数据丢一两帧无所谓，用reliable重传反而会堆积延迟。

所以你会遇到这种情况：命令行 ros2 topic echo 能看到数据（它默认兼容性很好），但自己写的订阅者收不到——因为你的订阅者用了默认的reliable，而发布端是best_effort。解决方法是订阅的时候显式指定QoS：

from rclpy.qos import QoSProfile, ReliabilityPolicy, HistoryPolicy

qos = QoSProfile(
    reliability=ReliabilityPolicy.BEST_EFFORT,
    history=HistoryPolicy.KEEP_LAST,
    depth=10
)
self.create_subscription(Image, '/camera/image_raw', self.cb, qos)

我在这上面浪费过整整一个下午。当时以为是相机没出图，反复重启驱动，最后用 ros2 topic info /camera/image_raw --verbose 才看到发布端的QoS是best_effort，改成匹配的立刻就好了。 这个命令强烈建议加到你的排查清单里。

4. 写出第一个自己的功能包：代码、构建与launch

跑通示例之后，下一步是写自己的包。这一节我按"决策—编码—构建—启动"的顺序讲，重点解释为什么这么做。

4.1 动手前先决定用C++还是Python

这个问题没有标准答案，但有几个判断依据。

选Python的情况 ：算法验证、快速原型、调用Python生态的库（比如深度学习推理）、对实时性要求不高的上层逻辑。Python写起来快，改一行不用等编译，调试体验好。

选C++的情况 ：高频数据处理、需要严格控制延迟、要和硬件驱动或已有C++库打交道、要部署到算力有限的嵌入式设备上。C++编译慢，但运行时开销小得多。

我一般的做法是 混合 ：感知和控制这种对性能敏感的用C++，状态机、任务调度、跟外部系统对接的用Python。ROS2本身就鼓励这种混合，不同语言的节点之间通信完全透明。

有个细节要注意： 同一个包里的可执行文件语言可以混，但构建系统不同 。C++包用 ament_cmake ，Python包用 ament_python ，一个包只能用一种。所以要混的话，建两个包。

创建命令分别是：

# C++包
ros2 pkg create --build-type ament_cmake my_cpp_pkg --dependencies rclcpp std_msgs

# Python包
ros2 pkg create --build-type ament_python my_py_pkg --dependencies rclpy std_msgs

--dependencies 这个参数很关键，它会把依赖自动写进 package.xml 和构建文件。我见过有人手写 package.xml 漏了依赖，编译时找不到头文件，报错的指向跟真实原因差得很远，排查半天。

4.2 最小可运行的发布者和订阅者

先给一个Python发布者的完整例子，每个部分我都标注了意图：

import rclpy
from rclpy.node import Node
from std_msgs.msg import String


class Talker(Node):
    def __init__(self):
        # 节点名会出现在 ros2 node list 里，全局唯一
        super().__init__('talker')
        # 队列深度10，缓存来不及发的消息
        self.pub = self.create_publisher(String, 'chatter', 10)
        self.count = 0
        # 定时器1秒触发一次，比 sleep 循环更符合ROS2的方式
        self.timer = self.create_timer(1.0, self.tick)

    def tick(self):
        msg = String()
        self.count += 1
        msg.data = f'hello ros2 {self.count}'
        self.pub.publish(msg)
        # 日志会带上节点名和时间戳，比print好查
        self.get_logger().info(msg.data)


def main():
    rclpy.init()
    node = Talker()
    try:
        rclpy.spin(node)   # 阻塞，直到收到退出信号
    except KeyboardInterrupt:
        pass
    finally:
        node.destroy_node()
        rclpy.shutdown()

对应的订阅者只改三处：把 create_publisher 换成 create_subscription ，回调函数里处理消息，去掉定时器。

这里有个新手常见的错误： 在回调函数里做耗时操作 。ROS2默认是单线程执行器，回调里如果跑一个两秒的计算，后面所有消息都会堆积。表现是"数据延迟越来越大"。解决办法是用多线程执行器，或者把重计算丢给单独的线程或节点。我建议在架构阶段就把重活拆出去，不要在一个回调里塞太多。

C++版本的结构类似，只是类型声明更严格：

auto pub = this->create_publisher<std_msgs::msg::String>("chatter", 10);
timer_ = this->create_wall_timer(
    std::chrono::seconds(1),
    std::bind(&Talker::tick, this));

编译C++包时， CMakeLists.txt 里必须正确声明可执行文件和依赖，漏了 find_package 或者 ament_target_dependencies ，编译能过但链接会失败，报一堆undefined reference。

4.3 launch文件把启动流程固定下来

节点多了之后，一个一个终端去敲 ros2 run 是灾难。launch文件的作用就是把这些启动动作写成一个脚本，一条命令全部拉起来，还能传参数。

Python格式的launch文件最常用，也最灵活：

from launch import LaunchDescription
from launch_ros.actions import Node


def generate_launch_description():
    return LaunchDescription([
        Node(
            package='my_py_pkg',
            executable='talker',
            name='talker',
            parameters=[{'publish_rate': 2.0}],
            output='screen',   # 日志打到当前终端
        ),
    ])

几个容易忽略的点：

• executable 不是文件名，是 setup.py 里 entry_points 注册的那个名字，这两个不一致是launch启动失败的高频原因。
• output='screen' 建议都加上，否则节点日志被吞掉，出问题你什么都看不到。
• launch文件本身要在 setup.py 的 data_files 里做安装配置，否则编译之后 ros2 launch 找不到它。

启动方式：

ros2 launch my_py_pkg talker.launch.py

如果报"package not found"或者"file not found"，先确认你是不是忘了 source install/setup.bash 。这个提醒在后面还会出现，因为它实在是太常见了。

4.4 colcon build失败的几个高频原因

编译报错信息通常很长，但真正有用的就那几行：第一个 error 和它下面的 Failed 。我的排查顺序是固定的：

报错特征	大概率原因	处理方式
找不到头文件	依赖没写进package.xml或CMakeLists	补依赖后重编
undefined reference	链接阶段少了库	检查ament_target_dependencies
找不到包名	没source install	source后重试
莫名其妙的旧行为	build/install缓存脏了	删掉重建
Python包改了代码不生效	忘了重新build	Python包也要build一次

关于最后一条我要强调： ROS2的Python包也需要 colcon build 。因为可执行文件是通过 install 目录的入口点启动的， src 里的改动不会自动生效。很多人第一次遇到"我明明改了代码怎么还是老样子"，就是这个原因。

还有个小技巧：编译时加 --symlink-install ，会让install目录建立符号链接指向src，Python文件改动后不用重新build直接生效，开发阶段非常省时间。

5. 可视化与仿真：RViz2、URDF、Gazebo和导航

前面都是看不见摸不着的数据流，这一节把它们变成你能看到的画面。视觉反馈对调试的价值极高，一个姿态错了的坐标系，用肉眼看三秒比查半小时日志快。

5.1 RViz2上手第一件事是改Fixed Frame

RViz2是ROS2的通用可视化工具，装desktop版本时已经自带了。启动：

rviz2

界面打开后左边是一堆配置项，右边是主视图。 新手最容易踩的坑是加了显示项却什么都看不到 ，原因通常只有一个： Fixed Frame 没设对。

Fixed Frame 是整个视图的参考坐标系，默认是 map 。如果你系统里只发布了 base_link 或 odom ，那么所有数据都会因为找不到 map 而被丢弃，界面上什么都不显示，而且 不会有任何弹窗提示 。

解决办法是在左侧 Global Options 里把 Fixed Frame 改成实际存在的坐标系。你可以用：

ros2 run tf2_tools view_frames

生成一张坐标系关系图，确认到底有哪些坐标系可用。这一步我建议养成本能，只要RViz2是空的，先查坐标系。

另外，添加显示项时要注意话题名。点 Add 之后选类型，比如 LaserScan ，然后在里面填话题。话题下拉框里能选到，说明话题存在；选不到，说明发布端没起来，先回去解决上游问题。

5.2 URDF描述模型，关节状态得有人来发

要让一个机器人模型在RViz2里显示出来，需要两样东西：模型的描述文件，以及关节角度数据。

URDF 是描述机器人结构的XML格式，写清楚有哪些连杆（link）、用什么关节（joint）连接、各自的位置和惯量。结构一复杂，URDF会变得又长又重复，所以实际项目里一般用 Xacro ，它是URDF的宏扩展，支持变量、数学运算和模块复用。

写URDF时的高频问题有三个：

• 关节树断了。每个link必须通过joint连到父级，最后收敛到一个根link，出现两个根或者有环就会报错。
• 惯量参数写成0。物理仿真会直接崩或者行为异常，静态显示倒是看不出来。
• 单位搞错。URDF统一用米和弧度，从CAD导出时单位是毫米的话，模型会大一千倍。

关节状态由谁发布 是另一个常见疑惑。URDF只是静态描述，机器人动起来要靠 /joint_states 话题驱动。仿真环境里由仿真器发布；真实机器人由驱动或编码器发布；如果只是想看看模型长什么样，可以用 joint_state_publisher_gui 手动拖滑块：

ros2 run joint_state_publisher_gui joint_state_publisher_gui

配合 robot_state_publisher 把关节角度转成坐标系变换，模型就能在RViz2里动起来：

ros2 run robot_state_publisher robot_state_publisher --ros-args -p robot_description:="$(xacro my_robot.urdf.xacro)"

5.3 Gazebo里模型不动或者看不到，按这个顺序查

Gazebo是物理仿真环境，把URDF丢进去就能让机器人在虚拟世界里跑。它的启动链路比纯可视化长，出错点也多。 ros2 launch 一跑，终端刷出一堆日志，很多人看到日志就不看了，其实关键信息都在里面。

排查顺序我一般是这样的：

第一，确认仿真器本身起来了。 Gazebo窗口应该出现，里面有地面和光照。没有窗口，就是环境或显卡问题，跟ROS2无关。

第二，确认模型加载进去了。 模型没出现，看日志里有没有解析URDF失败的报错。Gazebo对URDF的要求比RViz2严格，惯量缺失、mesh路径不对都会导致加载失败。

第三，确认插件加载成功。 要让模型受控制，需要在URDF里配插件。插件是编译出来的动态库，路径写错的话，Gazebo不会报错，只是模型像个石头一样不动。 这种"没有报错但不工作"的情况最坑人 ，所以日志里跟插件相关的行要重点看。

第四，确认时间同步。 仿真时间和真实时间不一致会导致参数不对、控制器报错。用：

ros2 param get /gazebo use_sim_time

确认为true。同时你的其他节点也要设成用仿真时间，否则会出现"定时器跑得飞快"这种诡异现象。

5.4 从建图到导航的启动顺序

SLAM和导航是ROS2里最常见的应用场景，也是启动最复杂的。启动顺序错了，会看到一堆参数报错，而且报错信息通常指向不到真正的原因。

比较稳妥的顺序是：

1. 先启动仿真环境或真实机器人驱动，确认 /scan 、 /odom 、 /tf 这三个基础话题都有数据。
2. 用 ros2 topic hz 确认雷达话题频率正常，一般10Hz左右。
3. 启动SLAM节点开始建图，用RViz2观察地图逐步成型。
4. 建完图保存地图，再切换到导航模式，加载地图文件启动导航栈。

导航相关的启动会拉起十几个节点，典型的一条命令形如：

ros2 launch nav2_bringup tb3_simulation_launch.py headless:=false

headless 这类参数控制要不要开图形界面，在服务器上跑的时候设成true能省资源。这类launch文件里参数极多，刚开始不建议逐个研究，先让它跑起来，再按需调整。

有几个必须知道的点：

• 坐标系必须是连通的。 map → odom → base_link 这条链任何一环断了，导航都会失败。用 view_frames 查。
• 雷达安装位置要如实配置。 URDF里雷达相对车体的偏移写错了，建出来的地图会有系统性的偏差，看起来"漂移"，其实是标定问题。
• 初始位姿要给。 导航启动后通常需要在RViz2里用工具手动指定机器人当前在地图上的位置，不给的话定位收敛不了。

6. 那些让人抓头的报错：完整排查链路

这一节把前面提到的坑集中梳理一遍，但重点不是给答案，而是展示 遇到陌生报错时怎么一步步缩小范围 。这个能力比记住任何一个命令都值钱。

6.1 command not found 的三层成因

ros2: command not found 几乎每个新手都会遇到，它的成因有三层，从简单到复杂依次排查。

第一层，环境变量没source。 打开新终端试试 echo $ROS_DISTRO ，没输出就是这个问题。临时解决是手动source一次，永久解决是写进 .bashrc 。

第二层， .bashrc 里的source路径不存在。 比如你换了ROS2版本， .bashrc 里还指向旧路径。表现是每次开终端都报一行"no such file or directory"，然后所有ROS2命令都不可用。这种报错很显眼，反而好解决。

第三层，装了两个版本，环境变量互相覆盖。 这个最难查，因为 echo $ROS_DISTRO 有输出， ros2 命令也能用，但某些包或者某些库找不到。原因是PATH和AMENT_PREFIX_PATH里混了两个版本的路径，按顺序命中了一个不完整的。解决办法是清掉 .bashrc 里多余的行，重新打开终端，用：

echo $AMENT_PREFIX_PATH

确认里面只有一个发行版的路径。

找到问题之后， 不要只改当前终端，要改 .bashrc ，否则下次开终端又回到原样。这是我最想提醒的一点。

6.2 两台机器互相看不见对方的话题

分布式通信是ROS2的强项，但"配置对了才强"。两台机器互相看不到，按下面的链路查。

先确认在同一网络。 互相 ping 一下，不通的话先解决网络。

再确认DOMAIN_ID一致。 ROS2默认域是0，如果两台机器的 ROS_DOMAIN_ID 不一样，它们就像在两个平行世界。这个变量本身就是为了隔离用的，同一网段里有多个团队在做项目时，各设各的域，互不干扰。

export ROS_DOMAIN_ID=7

然后确认DDS实现一致。 如果一台用Fast DDS，另一台用Cyclone DDS，默认配置下可能发现不了对方。排查时先统一到同一种实现，跑通之后再研究混合组网。

最后考虑组播问题。 DDS默认靠组播做节点发现，有些网络环境（尤其是一些受限的无线网络）会屏蔽组播。这时候需要配置DDS使用单播，或者指定发现服务器。这一层配置通常写在XML文件里，通过环境变量指向它：

export RMW_IMPLEMENTATION=rmw_fastrtps_cpp

坦白讲，跨机器通信是最容易让人怀疑人生的环节，因为它涉及网络、DDS配置、防火墙三个层面。我的建议是： 先在单机上把功能跑通，再引入第二台机器 ，每次只改一个变量。

6.3 单片机和micro-ROS场景的额外注意点

把ROS2的能力延伸到单片机上是很多人的需求——用一块开发板采集传感器数据，直接以ROS2节点的身份发布话题。micro-ROS就是干这个的，它把ROS2的客户端库裁剪到能跑在资源受限的设备上。

这类场景有几个跟纯软件不一样的坑：

第一，需要一个桥接代理。 单片机算力不够，跑不了完整的DDS，所以要在主机上跑一个代理进程，单片机通过串口或者网络跟它通信，代理再把数据接入ROS2网络。代理没起来，单片机的节点就"不存在"。

第二，串口权限。 Linux下访问串口设备通常需要权限，要么把用户加到对应的组里，要么配置udev规则。表现是程序报"permission denied"或者干脆打不开设备。这个问题在重启之后可能重现，所以 用udev规则永久解决 比每次 sudo 靠谱。

第三，波特率和设备名。 设备名像 /dev/ttyUSB0 这种，插拔顺序变了就会变。用设备的唯一标识（比如按序列号）建立固定名字的软链接，能避免"昨天还好好的今天就找不到设备"。

第四，数据类型要匹配。 单片机上资源紧张，消息类型定义得越简单越好。自定义消息要经过代码生成，链条比主机上长，任何一环版本不一致都会导致通信失败。

第五，构建工具链要独立。 单片机的编译跟主机上的 colcon 是两套东西，很多人在同一台机器上混着用，环境变量互相污染，出现一些莫名其妙的编译错误。我建议用容器把两套工具链隔离开，虽然多一步，但省心得多。VSCode配合插件是常见的组合，配置好之后体验还不错，但初次配置要花点时间在路径和编译器设置上。

6.4 排查这件事本身的方法论

写到这里，我想单独说说排查的方法，因为前面所有的具体案例都只是它的实例。

我的习惯是 先分层，再二分 。分层的意思是：把系统拆成硬件层、驱动层、通信层、算法层，先确定问题在哪一层。比如收不到雷达数据，先看驱动程序有没有输出（硬件层），再看话题有没有数据（通信层），最后才怀疑算法。二分的意思是：在确定的层面上，找中间点验证。比如怀疑是数据源问题还是订阅端问题，就用 ros2 topic pub 手动灌一条进去，一下子就能把范围切一半。

还有一个很实用的习惯： 改动一次只改一个地方 。同时改三个参数然后问题消失了，你根本不知道是哪个起的作用，下次遇到同样的问题还是不会。这个问题我在刚开始学的时候吃了不少亏。

最后，遇到报错先看日志的 第一行和最后一行 ，中间的大段堆栈信息通常只在特定场景有用。ROS2的日志格式里带了节点名和严重级别， ERROR 级别的一定要处理， WARN 的可以先记下来继续。

我在实际项目里最深的一个体会是：ROS2的入门门槛不在概念多，而在于它的错误反馈有时候很不直接——QoS不匹配不报错、坐标系缺失不报错、插件没加载也不报错，全靠你自己有一套排查流程。所以与其背命令，不如把上面这套"先看节点、再看话题、再看数据、最后看坐标系和QoS"的顺序变成肌肉记忆。另外就是那句说了好几遍的话： 改完代码记得 colcon build ，编译完记得 source install/setup.bash 。这两件事听起来简单到不值得提，但它们解决过我遇到的一半以上的"玄学问题"，包括那些折腾了半天最后发现只是忘了source的时刻。