企业官网建设流程全解析

1. 写在动手之前：从建图成功到稳定跑的差距在哪

很多搞AGV的朋友应该都有过这种经历：建图跑得挺顺，地图看着也漂亮，结果一切换到自动导航，小车就开始各种撞墙、原地转圈、莫名其妙急停。我最早接触AGV路径规划那阵子也是这样，后来把Python+ROS这套激光SLAM导航链路完整拆开调了一遍，才算真正弄明白问题出在哪。这篇文章就围绕AGV路径规划这个核心，把我用Python+ROS实现激光SLAM导航的完整过程，包括环境搭建、建图、导航框架、避障代码以及调参踩坑记录，一次性讲清楚。

这篇内容适合正在做AGV或者移动机器人项目的工程师，也适合准备入门ROS导航的朋友。你不需要有很深的路径规划算法功底，但最好对Linux基本命令和Python语法不陌生。我会把每一步都写明白：为什么这么做、不这么做会踩什么坑、出现故障怎么排查。整套方案我实机验证过，不是纸上谈兵，照着做能省掉不少弯路。

1.1 一个典型的AGV导航调试现场

我先描述一个场景：一台差速底盘AGV，头顶装一个单线激光雷达，工控机里跑着Ubuntu和ROS，任务是让它在仓库里从A点自主走到B点，避开托盘和货架。很多人拿到这个需求后的第一反应是“SLAM建个图，然后move_base发个目标点就行了”。理论上没错，但实际跑起来会发现：

• 建好的地图在Rviz里看没问题，导航时定位却时不时跳一下，车就开始画龙。
• 明明激光雷达已经扫到障碍物了，车还是硬往前顶，碰到之后才急停。
• 全局路径规划出来的轨迹绕远路，局部规划又频繁重新规划，车走走停停，效率很低。

这些问题的根源，往往不在某一个单独环节，而是整条链路——从激光数据处理、TF坐标变换、定位精度到代价地图参数、规划器配置——没有协同工作。所以我在后面的章节里，会按正常做项目时的推进顺序来讲：先搭环境，再建图，再搭导航框架，再补避障代码，最后集中调参。

1.2 这套方案的技术选型概览

在开始之前，我先交代一下这套方案的整体选型，后面所有步骤都基于这个组合：

为什么用Noetic而不是Humble？如果你是第一次搭这套系统，Noetic的社区资料最多，网上随便一搜就是现成的报错解决方案，对入门非常友好。ROS 2 Humble的实时性和通信机制确实更好，但很多传统AGV厂家的上层软件还是ROS 1的老接口，团队协作时版本壁垒很现实。我的建议是：学习阶段直接用Noetic，等整个导航链路跑通了，再迁到Humble不迟。

2. 环境准备最容易翻车的三个环节：ROS版本、Python环境与仿真平台

环境搭建是劝退新手最多的地方。我见过太多人卡在安装这一步，还没开始写代码就放弃了。所以这一节我把最容易翻车的环节单独拎出来，按顺序处理完，后面就顺利了。

2.1 ROS版本选择与系统安装

如果你用的是Ubuntu 20.04，ROS对应版本是Noetic；Ubuntu 22.04对应Humble（ROS 2）。这里有个关键点很多人会搞混：Ubuntu 18.04对应的是ROS Melodic，它的Python默认是2.7，跟现在大量Python 3的开源库不兼容。所以我现在的建议是，别用Melodic做新项目，除非你维护的是存量老车。

系统装好后，先把软件源和基础工具补齐：

sudo apt update sudo apt install -y git curl vim net-tools

然后设置ROS软件源并安装ROS Noetic完整版桌面版。这一步如果你挨个敲API key和源地址，很容易因为网络问题卡住。我这边实测省心的方法是用网络上常见的ROS安装脚本，比如鱼香ROS的一键安装脚本。它其实就是个bash脚本，会自动识别你的Ubuntu版本、配置源、安装ROS和常用依赖，运行方式：

wget http://fishros.com/install -O fishros && . fishros

脚本运行后会让你选择安装内容，比如ROS Noetic完整版、ROS 2 Humble、或者Gazebo仿真，按数字键选择就行。这个脚本的价值在于，它把源配置、公钥导入、rosdep初始化这些琐碎但容易出错的步骤全部封装了。我第一次手动配置时卡在公钥导入上，用这个脚本十分钟就装完了。装完之后记得初始化rosdep：

sudo rosdep init rosdep update

rosdep的作用是编译工作空间时自动解析依赖包，这一步不执行，后面catkin_make的时候会报各种找不到依赖的错误。

2.2 Python环境配置

ROS Noetic的Python版本是Python 3.8，系统自带的python3就能满足大部分需求。我在项目里习惯用venv给机器人代码建独立虚拟环境，避免跟系统Python装包时互相冲突。但注意一点：ROS节点的执行依赖系统Python环境里的rospy包，所以你不能直接在虚拟环境里跑ROS节点，除非在创建虚拟环境时加--system-site-packages参数：

sudo apt install -y python3-venv python3-pip python3 -m venv --system-site-packages ~/agv_env source ~/agv_env/bin/activate

这样虚拟环境既能用系统装好的rospy，又能用pip安装numpy、matplotlib这些做路径规划算法验证的库。如果你用VSCode做开发，记得在.vscode/settings.json里把Python解释器路径指向~/agv_env/bin/python，不然调试时import rospy会报错。

另外我强烈建议装上rospy-tutorials和tf2-tools这两个包，调试TF坐标变换时非常有用：

sudo apt install -y ros-noetic-rospy-tutorials ros-noetic-tf2-tools

2.3 建一个工作空间并准备Gazebo仿真环境

没有真车的时候，先在Gazebo里建一个仿真AGV模型调通整条链路，是最稳妥的做法。先创建工作空间：

mkdir -p ~/agv_ws/src cd ~/agv_ws catkin_make source devel/setup.bash echo "source ~/agv_ws/devel/setup.bash" >> ~/.bashrc

Gazebo和导航相关依赖包一次装齐：

sudo apt install -y ros-noetic-gazebo-ros ros-noetic-gazebo-plugins ros-noetic-navigation ros-noetic-slam-gmapping ros-noetic-amcl ros-noetic-map-server ros-noetic-move-base ros-noetic-dwa-local-planner

这里解释一下为什么要装navigation这个元包。它会一并安装move_base、amcl、map_server、costmap_2d这些导航核心组件，省得一个一个找。Gazebo里跑仿真时，激光雷达模型通常给的是sensor_msgs/LaserScan话题，这个格式跟后面避障代码直接匹配，所以在仿真环境里把逻辑调通，换真机时只需要改驱动话题名和几个参数就行。

3. 激光SLAM建图的完整链路：从激光驱动到地图文件

SLAM建图是整个导航系统的地基。地图不准，后面AMCL定位神仙难救。所以这一章我会把选型、实操、以及容易忽略的坐标系检查都写明白。

3.1 激光SLAM选型：gmapping、cartographer、slam_toolbox怎么选

激光SLAM算法选型是很多人会纠结的地方。我的经验是：AGV运行场景基本是结构化环境，墙壁规则、通道固定，用gmapping就足够了。它依赖里程计，计算量小，在低配工控机上也能跑30Hz以上。Cartographer精度确实更高，能处理长廊等退化场景，但CPU占用大，参数多，调起来费时间。slam_toolbox的优势是支持建图后的地图修正和重定位，适合二次开发。

我给的结论是：第一套方案用gmapping把流程跑通，遇到长廊建图漂移再切cartographer。这跟我做项目的习惯一致——先用最简方案验证系统，再针对具体痛点升级。

启动gmapping的方式很简单，前提是你的激光雷达驱动已经正常发布/scan话题。一个可以直接用的launch文件：

<launch> <node name="slam_gmapping" pkg="gmapping" type="slam_gmapping"> <param name="base_frame" value="base_footprint"/> <param name="odom_frame" value="odom"/> <param name="map_frame" value="map"/> <param name="map_update_interval" value="5.0"/> <param name="maxUrange" value="6.0"/> <param name="maxRange" value="8.0"/> <param name="minimumScore" value="50"/> <param name="linearUpdate" value="0.1"/> <param name="angularUpdate" value="0.1"/> <remap from="scan" to="scan"/> </node> </launch>

注意参数里base_frame要跟你机器人的TF树里的base坐标系名称一致。如果你用的模型是base_link而不是base_footprint，这里不对应的话，gmapping会一直报“Couldn't get base frame”之类的错误，地图完全建不起来。

3.2 建图实操流程与命令

建图过程分三步：启动雷达驱动、启动SLAM算法、遥控小车扫描环境。以仿真环境为例：

# 终端1：启动Gazebo仿真环境和AGV模型 roslaunch agv_gazebo agv_world.launch # 终端2：启动gmapping roslaunch agv_slam gmapping.launch # 终端3：启动键盘遥控 rosrun teleop_twist_keyboard teleop_twist_keyboard.py

操作手法上有讲究：不要只沿着墙根转一圈就完事。正确做法是先在场地中央转一圈让地图初始化，然后沿着场地边界慢速走一圈，再以S形路线扫内部，遇到柱子之类的障碍物要绕一圈让它形成闭合轮廓。建图速度控制在0.3m/s以内，转弯时尽量原地转，别大幅画弧——弧线会让gmapping的扫描匹配误差累积，导致地图重影。

我建图时习惯打开Rviz实时看地图和激光点云叠合情况：

rosrun rviz rviz -d $(rospack find agv_slam)/rviz/slam.rviz

如果激光点云和地图边缘出现明显错位，说明里程计标定不准或者雷达安装位置描述有误，先别急着继续扫，停下来检查机器人底盘的/odom话题频率和TF树。

3.3 保存地图与坐标系检查

建图完成后保存地图：

rosrun map_server map_saver -f ~/agv_ws/src/agv_nav/maps/warehouse

这会生成两个文件：warehouse.yaml和warehouse.pgm。别忘了看一眼yaml里的resolution和origin参数，这两个值在后续导航配置里会被map_server读取，写错了地图加载后位置会偏。

保存完地图，务必做一件事：检查TF树。用自带的tf工具：

rosrun tf view_frames evince frames.pdf

正常情况TF树应该是一条完整的链：map -> odom -> base_footprint -> base_link -> laser。很多奇怪问题——比如车定位漂移、导航路径偏斜——最后查下来都是因为laser坐标系到base_link的静态坐标变换写错了。雷达装在车体中心正上方10cm处，那laser到base_link的xyz变换就应该是(0, 0, 0.10)，yaw偏角差0.01弧度，在10米外就是10厘米的位置误差，足够让车撞上货架。所以建图之前，静态坐标变换必须反复确认。

4. 导航框架拆解：move_base、AMCL与代价地图的分工逻辑

建好图之后，接下来就是把导航框架跑起来。很多新手觉得导航就是发一个目标点，车自己会走。真实系统里，一套标准导航链路涉及多个节点协同工作，理解它们各自干什么，排查问题才能有的放矢。

4.1 导航系统里每个节点在干什么

我把一条完整的导航数据流拆成五个角色：

1. map_server：加载建好的地图，持续发布/map话题。
2. AMCL：负责定位。它接收激光雷达数据、里程计数据和地图，通过粒子滤波估计机器人在地图中的位姿，发布/amcl_pose和map->odom的TF变换。
3. move_base：导航总指挥。它订阅目标点/move_base_simple/goal，内部由全局规划器和局部规划器协作，最终输出速度指令到/cmd_vel。
4. costmap_2d：代价地图生成器。它把地图数据和激光雷达实时数据融合成“障碍物栅格图”，供规划器搜索路径时使用。
5. RViz：可视化调试工具，相当于导航系统的“仪表盘”。

很多人会问：AMCL都定位了，为什么还要维护map->odom这个变换？原因是：里程计会有累积误差，AMCL每次用激光匹配修正一次位置，这个修正量就体现在map->odom变换里。如果这个变换跳变剧烈，就说明定位不稳定，需要检查AMCL参数或者激光数据质量。

启动这一整套的launch文件结构，建议拆成两个：amcl.launch和move_base.launch，方便单独重启调试。

4.2 代价地图参数与障碍物膨胀

costmap是路径规划里非常核心但又容易被忽视的部分。它分全局代价地图/global_costmap和局部代价地图/local_costmap，各有各的坐标系和更新频率。下面是我常用的一套costmap配置，直接放到config/costmap_common.yaml里：

robot_base_frame: base_footprint update_frequency: 5.0 publish_frequency: 2.0 transform_tolerance: 0.5 static_map: false rolling_window: true width: 6.0 height: 6.0 resolution: 0.05 obstacle_range: 3.0 raytrace_range: 3.5 inflation_radius: 0.35 cost_scaling_factor: 3.0 observation_sources: laser laser: data_type: LaserScan topic: /scan marking: true clearing: true

这里有两个参数直接影响避障效果，我解释一下背后逻辑：

• inflation_radius：障碍物的“膨胀半径”。数值越大，AGV离障碍物越远，路径更安全但更绕。对于1米宽的AGV，我给0.35米起步，实际调试时再根据货架间距调整。
• cost_scaling_factor：代价衰减速度。值越小，代价衰减越慢，也就是说靠近障碍物的区域代价更高。调到3.0是我的经验值，既能保持一定通行距离，又不会让狭窄通道完全不可通行。

还有clearing: true这个配置很关键，它让激光雷达的每个扫描点不仅把障碍物标记进地图，还把障碍物后方的“空白区域”清除掉。代价地图默认会清除动态障碍物离开后的痕迹，clearing就是干这个的。如果你发现小车在经过一个地方后，路线上保留着“虚拟障碍物”导致后续路径绕路，多半就是这个参数没配对。

4.3 全局与局部路径规划器的选型

move_base默认的全局规划器是navfn，它实现的是Dijkstra算法；也可以切换到global_planner插件使用A*算法。两者都能找出一条从起点到目标点的路径，区别在于：

• Dijkstra：从起点出发向外扩展，遍历整个地图直到找到终点，一定能找最优路径，但搜索范围大、耗时长。
• A*：在Dijkstra基础上加入启发式函数，相当于“朝着目标方向优先搜索”，速度快很多，适合仓储AGV这种需要频繁规划路径的场景。

我现在的做法是在move_base参数里显式指定使用A*：

GlobalPlanner: use_grid_path: false use_quadratic: true use_dijkstra: false use_astar: true default_tolerance: 0.0

局部规划器我选了DWA。它的原理其实很直白：在机器人当前速度附近采样一组候选速度，用运动学模型模拟一小段时间内的轨迹，然后根据“离全局路径多远、是否撞障碍物、是否朝目标”这几个指标打分，选分数最高的速度执行。

DWA适合差速和全向底盘，参数少，调起来快。TEB（时间弹性带）的避障能力更强，生成的轨迹更平滑，但它会时刻优化时间最优性，调不好容易出现抖动。如果你是阿克曼底盘的AGV，建议用TEB；差速底盘用DWA就够，没必要一开始就上TEB给自己增加调参负担。

5. 避障代码核心实现：从激光数据到速度指令

标题里说要附避障代码，这一段就上干货。我先说明设计思路：不自己重写一套路径规划，而是做一个“安全控制器”，串在move_base和底盘之间。也就是说，move_base算出速度指令，这个节点先检查激光数据，确认前方安全再放行，有碰撞风险就拦截、减速或转向。这样设计的好处是，既不影响move_base的完整规划能力，又能在传感器数据异常或规划器漏判时兜底，工程上更稳。

5.1 代码逻辑与数据结构

这个节点的核心是维护两个数据源：

• /move_base/cmd_vel（geometry_msgs/Twist）：move_base规划好之后发出来的目标速度。
• /scan（sensor_msgs/LaserScan）：激光雷达的实时扫描数据。

收到目标速度后，先看机器人前进方向附近有没有障碍物。具体做法是把激光点云按角度分成三个扇区：

• 前方：-30°到+30°，用于判断是否能继续前进。
• 左侧：+30°到+90°，用于左转避让时判断左侧空间。
• 右侧：-90°到-30°，用于右转避让时判断右侧空间。

每个扇区取最小距离作为“该方向的安全距离”。当前方距离小于安全阈值时，就把move_base发给底盘的线速度压到0，同时根据左右哪边空间更宽裕，给一个小的转向角速度。这样既实现了避障，也保持了继续绕障碍物走的能力，而不是傻站在那。

5.2 可运行的Python避障节点源码

下面是我实机上跑过的版本，完整可以放到scripts/obstacle_avoidance.py里直接运行：

#!/usr/bin/env python3 import rospy import math from sensor_msgs.msg import LaserScan from geometry_msgs.msg import Twist class ObstacleAvoidance: def __init__(self): rospy.init_node('obstacle_avoidance', anonymous=True) self.cmd_pub = rospy.Publisher('/cmd_vel', Twist, queue_size=1) rospy.Subscriber('/move_base/cmd_vel', Twist, self.cmd_callback) rospy.Subscriber('/scan', LaserScan, self.scan_callback) self.latest_scan = None self.safety_dist = rospy.get_param("~safety_dist", 0.35) self.turn_speed = rospy.get_param("~turn_speed", 0.5) self.emergency_stop_dist = rospy.get_param("~emergency_stop_dist", 0.20) self.lateral_dist = rospy.get_param("~lateral_dist", 0.30) self.rate = rospy.Rate(20) rospy.loginfo("Obstacle avoidance node started.") def scan_callback(self, msg): self.latest_scan = msg def get_sector_distance(self, angle_min, angle_max): if self.latest_scan is None: return float('inf') ranges = self.latest_scan.ranges angle_min = max(angle_min, self.latest_scan.angle_min) angle_max = min(angle_max, self.latest_scan.angle_max) idx_min = max(0, int((angle_min - self.latest_scan.angle_min) / self.latest_scan.angle_increment)) idx_max = min(len(ranges) - 1, int((angle_max - self.latest_scan.angle_min) / self.latest_scan.angle_increment)) valid = [r for r in ranges[idx_min:idx_max + 1] if r > 0.1] if not valid: return float('inf') return min(valid) def cmd_callback(self, msg): if self.latest_scan is None: self.cmd_pub.publish(msg) return front_dist = self.get_sector_distance(-math.radians(30), math.radians(30)) left_dist = self.get_sector_distance(math.radians(30), math.radians(90)) right_dist = self.get_sector_distance(-math.radians(90), -math.radians(30)) if front_dist < self.emergency_stop_dist: # 紧急停车：线速度为0，角速度为0 stop = Twist() self.cmd_pub.publish(stop) rospy.logwarn_throttle(1.0, "Emergency stop! front_dist=%.2f", front_dist) return if front_dist < self.safety_dist and msg.linear.x > 0: # 前方太近，需要减速并转向 avoid = Twist() avoid.linear.x = 0.0 if left_dist > right_dist: avoid.angular.z = self.turn_speed else: avoid.angular.z = -self.turn_speed self.cmd_pub.publish(avoid) rospy.logwarn_throttle(1.0, "Avoiding obstacle, front=%.2f", front_dist) return # 安全，透传move_base的指令 self.cmd_pub.publish(msg) def spin(self): r = rospy.Rate(20) while not rospy.is_shutdown(): r.sleep() if __name__ == '__main__': try: node = ObstacleAvoidance() node.spin() except rospy.ROSInterruptException: pass

解释几个关键设计：

• 为什么用rospy.logwarn_throttle而不是直接rospy.logwarn？因为避障触发时这个回调函数以20Hz触发，直接打印会把终端刷爆，throttle让它每秒最多打印一次，既能看到日志又不影响实时性。
• 为什么在cmd_callback里发布指令而不另开定时器？因为避障节点本质是个“阀门”，只有在move_base有速度指令进来时才需要响应，没有目标时就不该有任何输出。
• 扇区距离计算那里有个细节：r > 0.1这个过滤不能省。激光雷达在检测到过近物体或者没有回波时，会用0或者inf填充，直接参与min计算会得到错误结果。

5.3 如何与move_base配合工作

把这个节点接到系统里，核心是话题重映射。默认情况下move_base发布到/cmd_vel，我们改成让它发布到/move_base/cmd_vel，然后由避障节点过滤后输出到真实的/cmd_vel：

roslaunch move_base move_base.launch cmd_vel_topic:=/move_base/cmd_vel rosrun agv_nav obstacle_avoidance.py

如果你不想改move_base的启动参数，也可以用rosrun topic_tools relay做话题转发，但那样控制粒度不够，避障节点就没法拦截了。我建议还是用重映射的方式。

这套代码的调试技巧：先在Gazebo仿真里跑，故意把障碍物放在路径中间，观察小车是否能停下并绕行。仿真里验证通过后，真机上把safety_dist从0.5开始往下调，逐步逼近AGV的最小通过能力。比如你的AGV底盘宽度0.6米，货架通道宽度0.8米，那safety_dist设0.15就够了，设太大反而会让小车在窄通道里进退两难。

6. 实测调参与避坑记录

最后一章，我把做AGV导航项目以来遇到的高频问题和调试经验汇总一下。这些问题在文档里往往看不到，但实际项目中几乎每个都会碰到。

6.1 激光雷达安装位置与TF坐标系

激光雷达的安装位置对导航稳定性影响极大。我吃过一次大亏：一台AGV的雷达装在车体正前方，结果导航时一接近货架边缘，AMCL定位就疯狂跳变。后来排查发现，雷达视角朝前，侧面货架进入视野的角度太小，匹配特征不足，粒子滤波就乱猜。

正确做法是：雷达尽量装在车体旋转中心的正上方，这样才能保证雷达坐标系到base_link的变换里只有xyz平移，没有额外的旋转耦合。装好之后，用下面这条命令验证静态变换：

rosrun tf2_ros static_transform_publisher 0 0 0.10 0 0 0 base_link laser

yaw角的偏差即使只有几度，也会导致建图时墙壁倾斜、导航时路径偏移。真机调试时，先在RViz里观察激光点云是否跟小车模型的外轮廓对齐，这是最直观的检查方式。

6.2 导航跑飞、原地打转、突然急停的三类常见问题

我把实际调试中遇到的三类问题整理成了排查表，遇到类似情况可以直接对照检查：

这里面定位问题占了绝大多数。AMCL的初始位姿如果给错了，后面再怎么调参数都没用。我的习惯是启动导航后第一步先在RViz里手动给初始位姿，观察到激光点云与地图边缘基本对齐后，再发送导航目标点。别偷懒省这一步，省掉的这三分钟可能换来半小时的烦恼。

6.3 一份我常用的参数备份习惯

调参是AGV导航开发里最耗时也最容易反复的部分。我一开始也是看到哪个参数不对劲就随手改，结果反复改来改去，根本不知道哪一次改动真正起了作用。后来我给自己定了一个“每调必备份”的规矩：

1. 工作空间用git管理，所有配置文件进版本库。
2. 每次调参只改动一个变量，改完立刻记录效果和截图。
3. 参数文件命名带版本号和日期，比如costmap_20250115_v1.yaml、costmap_20250115_v2.yaml。
4. 调好一批参数后，在Rviz里保存一个Bookmarks位置，方便回看。

这套习惯帮了我大忙。有一次在客户现场调了大半天的参数，晚上回去复盘，就是靠git历史记录查到了关键改动是哪一行。

最后再分享一个我自己的习惯：每次拿到一台新的AGV，我不会直接开始调导航参数，而是先花半天时间把底盘的直线精度和旋转精度摸清楚。对着墙上贴一张纸，让车跑1米，用卷尺量；让车原地转360度，看偏差。底盘本身不准的话，SLAM建图、AMCL定位、路径规划全是空中楼阁，调起来事倍功半。把基础硬件的行为摸透，后面软件层的调试才会顺。