Nav2 核心参数配置 yaml 模板说明

2026/7/12 19:25:13

在 ROS 2 的导航框架 Navigation2 (Nav2) 中，整个系统的行为完全由一个统一的nav2_params.yaml配置文件驱动。一个工业级的参数配置，核心在于平衡代价地图（Costmap）的膨胀半径、全局/局部规划器的计算频次以及轨迹跟踪控制器的平滑度。

工业两轮差速 AMR 调优、生产环境可直接复用的 Nav2 核心参数配置 yaml 模板与深度中文逐行拆解说明。

一、工业级 Nav2 核心参数配置文件模板 (`nav2_params.yaml`)

amcl: ros__parameters: use_sim_time: false # 1. 蒙特卡洛定位粒子群配置 min_particles: 500 # 粒子数下限，过少会导致定位易丢失 max_particles: 2000 # 粒子数上限，过大会导致 CPU 占用率过高 alpha1: 0.2 # 轮式里程计旋转噪声系数 alpha2: 0.2 # 轮式里程计平移噪声系数 pf_err: 0.05 pf_z: 0.99 # 2. 坐标系定义 base_frame_id: "base_link" # 机器人底盘物理中心坐标系 odom_frame_id: "odom" # 里程计坐标系 global_frame_id: "map" # 全局地图坐标系 scan_topic: "scan" # 激光雷达订阅的话题 global_costmap: global_costmap: ros__parameters: update_frequency: 1.0 # 全局地图更新频率（Hz），静态地图无需高频更新，节省算力 publish_frequency: 1.0 # 可视化话题发布频率 global_frame: "map" robot_base_frame: "base_link" use_sim_time: false robot_radius: 0.3 # 机器人的物理外接圆半径（米） plugins: ["static_layer", "inflation_layer"] # 全局地图图层 static_layer: plugin: "nav2_costmap_2d::StaticLayer" map_topic: "map" inflation_layer: plugin: "nav2_costmap_2d::InflationLayer" cost_scaling_factor: 3.0 # 膨胀衰减因子，越小坡度越缓，小车离障碍物越远 inflation_radius: 0.65 # 核心参数：全局安全膨胀半径（米），必须大于机器人半径 local_costmap: local_costmap: ros__parameters: update_frequency: 5.0 # 局部地图更新频率（Hz），必须高频以捕捉动态障碍物 publish_frequency: 2.0 global_frame: "odom" # 局部地图通常以 odom 为基准，防止 map 跳变引发抖动 robot_base_frame: "base_link" use_sim_time: false rolling_window: true # 开启滚动窗口，局部地图随机器人移动而移动 width: 3.0 # 局部地图物理宽度（3米） height: 3.0 # 局部地图物理高度（3米） resolution: 0.05 # 栅格分辨率（5厘米/格） plugins: ["obstacle_layer", "inflation_layer"] obstacle_layer: plugin: "nav2_costmap_2d::ObstacleLayer" enabled: true observation_sources: scan scan: topic: /scan max_obstacle_height: 2.0 clearing: true # 实时清除雷达扫不到的过期障碍物 marking: true # 实时标记新出现的障碍物 raytrace_max_range: 3.0 raytrace_min_range: 0.0 obstacle_max_range: 2.5 obstacle_min_range: 0.0 inflation_layer: plugin: "nav2_costmap_2d::InflationLayer" cost_scaling_factor: 5.0 # 局部膨胀衰减，较陡峭，允许小车更灵活地扭动避障 inflation_radius: 0.45 # 局部安全避障半径（米） planner_server: ros__parameters: expected_planner_frequency: 1.0 planner_plugins: ["GridBased"] GridBased: plugin: "nav2_navfn_planner::NavFnPlanner" # 经典的 A* / Dijkstra 全局规划器 use_astar: true # 开启 A* 寻路，比 Dijkstra 效率更高速度更快 allow_unknown: false # 严禁小车穿过未建图的未知未知区域（灰色区域） controller_server: ros__parameters: controller_frequency: 20.0 # 核心参数：局部控制器控制频率（Hz），工业标准 20-50Hz min_x_velocity_threshold: 0.001 min_y_velocity_threshold: 0.0 min_theta_velocity_threshold: 0.001 failure_tolerance: 0.3 # 容错时间（秒）：急弯处允许寻路失败的最长时限 progress_checker_plugin: "progress_checker" goal_checker_plugin: "goal_checker" controller_plugins: ["FollowPath"] progress_checker: plugin: "nav2_controller::SimpleProgressChecker" required_movement_radius: 0.1 # 机器人必须在 3 秒内移动 0.1 米 movement_time_allowance: 3.0 # 否则判定为被卡死（Stuck），触发行为树重头恢复 goal_checker: stateful: True plugin: "nav2_controller::SimpleGoalChecker" xy_goal_tolerance: 0.05 # 到达终点的位置容差（5厘米） yaw_goal_tolerance: 0.08 # 到达终点的角度容差（约4.5度） FollowPath: # 调用工业量产最多的现代 Regulated Pure Pursuit 轨迹跟踪器 plugin: "nav2_regulated_pure_pursuit_controller::RegulatedPurePursuitController" desired_linear_vel: 1.2 # 期望最大线速度 (m/s) max_angular_vel: 2.0 # 期望最大角速度 (rad/s) min_approach_linear_vel: 0.05 # 接近终点时的保底爬行线速度 (m/s) lookahead_time: 1.5 # 前视时间公式：Lookahead_Dist = Speed * lookahead_time min_lookahead_dist: 0.3 # 最小前视距离限制（米），防止低速摆动 max_lookahead_dist: 0.9 # 最大前视距离限制（米），防止过弯切内线 use_regulated_linear_vel_scaling: true # 开启急弯自动减速 regulated_linear_vel_scaling_min_radius: 0.9 # 转弯半径小于 0.9 米时开始减速 regulated_linear_vel_scaling_min_speed: 0.1 # 过弯保底爬行车速 use_rotate_to_heading: true # 核心开关：大角度转弯时，开启原地自转 rotate_to_heading_min_angle: 0.785 # 航向误差超过 45 度时，原地自转对齐路径 rotate_to_heading_angular_vel: 1.5 # 原地自转时的旋转速度 (rad/s) use_cost_regulated_linear_vel_scaling: true # 靠近障碍物时自动减速

二、工业级调参避坑金律

膨胀半径的黄金不等式（防止小车无路可走）
在配置inflation_radius时，必须严格遵循以下几何约束：
$$\text{robot\_radius（机器人半径）} < \text{local\_costmap 膨胀半径} < \text{global\_costmap 膨胀半径}$$
原因：全局膨胀半径大，可以让全局规划器在宏观上选择最宽敞、最安全的道路；局部膨胀半径小，可以保证小车在现场遭遇临时加塞障碍物时，依然敢于贴近边缘滑行过去，而不会直接报错放弃。
局部更新频率与控制频率的“节拍对齐”
- local_costmap -> update_frequency（局部地图更新频率）建议设为 5.0Hz - 10.0Hz。
- controller_server -> controller_frequency（速度发布频率）建议设为 20.0Hz。
- 避坑说明：发布频率必须大于地图更新频率。这样可以保证控制引擎（如 RPP）高频输出指令消除打滑产生的机械延迟，但底层的传感器代价地图没必要刷新那么快，防止吃满车载 CPU。
大角度自转功能的引入（use_rotate_to_heading）
两轮差速 AMR 在工业车间直角弯（如直角路口、货架尽头）落地时，必须开启该功能。如果关闭该参数，小车在面临 90 度直角时会试图走一个“大圆弧”，这极易导致小车的车屁股或侧面雷达盲区撞上两边的墙壁。