2. Nav2参数系统深度解析

Nav2的“参数”并不是散落在各个节点里的常量，而是一套由ROS 2参数服务器统一托管、由YAML文件声明、由启动文件与命令行逐层覆盖、并可在运行时通过服务动态修改的分层配置体系。理解这套体系，是判断“路径为什么走不出来”的前提——因为绝大多数导航故障，最终都能追溯到某个参数在某一层被错误赋值，或被另一层意外覆盖。

一、参数服务器：节点级键值存储与命名空间

ROS 2中每个节点拥有独立的参数集合，参数以“节点名 + 参数名”为键，值支持bool、int、double、string、数组等类型。Nav2的控制器、规划器、代价地图、行为树导航器等都是独立节点，因此参数天然按节点隔离。节点名中的命名空间会参与键的构成，例如/robot1/controller_server与/robot2/controller_server的同名参数互不影响，这正是多机器人共用一套Nav2配置的基础。

需要强调的是，参数服务器只负责“存储与分发”，它不会校验参数语义。把robot_radius写成负数、把max_vel_x写成0，服务器照单全收，错误要到代价地图膨胀或速度采样阶段才暴露。因此参数正确性必须靠YAML结构约束和运行时校验来保证。

二、YAML配置文件结构：三层嵌套

Nav2标准YAML采用三层结构：最外层是节点名（可带命名空间），第二层是ROS参数名，第三层是具体值。一个典型片段如下：

controller_server:
  ros__parameters:
    controller_frequency: 20.0
    FollowPath:
      plugin: "dwb_core::DWBLocalPlanner"
      max_vel_x: 0.45
      min_vel_x: 0.0
      max_vel_theta: 1.0
      xy_goal_tolerance: 0.15

local_costmap:
  local_costmap:
    ros__parameters:
      robot_radius: 0.22
      inflation_layer:
        inflation_radius: 0.55
        cost_scaling_factor: 3.0

这里有两个容易出错的细节。第一，ros__parameters是固定关键字（注意是两个下划线），写成ros_parameters会导致整段参数被忽略，节点回退到默认值。第二，代价地图节点存在“节点名/命名空间”双层同名结构（local_costmap: local_costmap:），这是Nav2为支持多代价地图实例设计的，漏写内层会使robot_radius不生效，进而让机器人以默认半径规划，出现贴墙或过窄通道无法通过的现象。

插件参数（如FollowPath下的DWB参数）挂在插件命名空间下，只有plugin字段正确声明了插件类型，其下参数才会被该插件读取。插件名拼错时，控制器服务器启动即报“plugin not found”，属于启动期故障，容易发现；而插件名正确但参数名拼错（如max_vel_x写成max_velx），则会被静默忽略，属于运行期隐性故障，危害更大。

三、参数覆盖机制：从默认值到命令行

一个参数最终生效的值，遵循“默认值 < YAML文件 < 启动文件中的参数字典 < 命令行--ros-args -p”的优先级顺序，后者覆盖前者。启动文件通过parameters=[yaml_path, {'node': {'param': value}}]的方式叠加，列表中越靠后的来源优先级越高。这一机制在调试时非常有用：不必改YAML，直接用命令行临时覆盖单个参数验证假设。

ros2 run nav2_controller controller_server \
  --ros-args --params-file nav2_params.yaml \
  -p controller_frequency:=10.0

排查覆盖问题时，可用ros2 param get /controller_server controller_frequency读取运行时真实值，再与YAML中写的值比对。若两者不一致，说明存在更高优先级的覆盖源；若一致但仍不符合预期，则问题在参数语义而非覆盖链。

四、动态重配置接口

Nav2节点普遍注册了参数回调，支持运行时修改。通过ros2 param set或/set_parameters服务即可生效，无需重启节点：

ros2 param set /local_costmap/local_costmap inflation_layer.inflation_radius 0.65
ros2 param set /controller_server FollowPath.max_vel_x 0.30

动态修改的价值在于快速验证：当机器人频繁擦碰障碍时，可临时调大膨胀半径观察行为变化，确认是膨胀不足还是路径跟踪偏差。但要注意，并非所有参数都支持热更新——插件类型、地图分辨率、坐标系名等结构性参数通常需要重启；而速度、容差、膨胀半径、代价缩放因子等数值参数一般可动态生效。修改后应通过ros2 param get确认写入成功，并观察代价地图话题是否刷新。

五、参数错误如何引发路径故障

把参数错误与路径故障对应起来，能显著缩短排障时间。典型映射如下：robot_radius偏小或inflation_radius不足，代价地图膨胀层过薄，规划器会给出贴墙路径，表现为“能走但总擦碰”；xy_goal_tolerance过大，机器人提前判定到点，表现为“停在目标附近不动”；max_vel_x为0或min_vel_x大于max_vel_x，速度采样无可行解，控制器报“no valid control”，表现为原地不动或频繁重规划；controller_frequency过低，跟踪滞后，表现为过弯外偏。

还有一类隐蔽故障来自YAML层级错误：参数写在了错误的节点名下，节点读取不到便使用默认值，而默认值往往“看起来能用”，导致问题难以复现。此时应先用ros2 param list /节点名确认参数是否真的挂在该节点上，再逐项比对。

综上，Nav2参数体系的关键在于“分层来源 + 节点隔离 + 运行时可变”。排障时不要只盯着YAML文本，而要沿着覆盖链读取运行时真实值，再结合插件命名空间与参数语义判断其是否会引发具体的路径异常。把这条链路走通，参数问题就从“玄学”变成了可定位、可验证的工程问题。