简介：面向 Python 学习者、机器人或人工智能相关课程的学生，这份项目源码包完整展示了机器人自动走迷宫的解决方案，可用作课程设计、期末大作业或毕业设计的参考模板。资源包共 3 个文件，体积约 535KB，内含可直接运行的 Python 核心程序、便于快速上手的说明文档，以及一份完整的 Word 版设计报告，程序与文字材料相互配套，覆盖迷宫环境构建、机器人移动控制、寻路逻辑实现与项目整理等核心环节。项目已经过导师指导，获 97 分高分，源码无需修改即可运行，适合需要快速复现一个完整走迷宫项目、深入学习路径搜索思路，或是补交课程报告的学习者。目前已有 156 人学习下载，代码结构清晰、文档流程完备，可直接用于提交课程设计或作为答辩展示内容。

1. 自动走迷宫不是一条A*到底：感知、规划与控制先拆开再动手

“基于Python实现的机器人自动走迷宫”这个标题看起来像课设练习，但真正动手做你会发现，难的从来不是求解迷宫的算法，而是让一个带传感器的虚拟小车在弯道里不偏、不撞、不掉进死循环。位姿不准的时候，A*算出的最短路径只是纸面路径；传感器有噪声的时候，墙跟随反而比全局规划更稳。这篇笔记按一条最常用的工程主线展开：先把迷宫建模成栅格地图，接着选寻路算法，再做转向控制，最后把常见翻车点挨个列出来。适合正在做课设、毕设或刚接触机器人导航的人，也适合想把源码整理成能演示、能复盘文档的朋友。

2. 把迷宫变成Python能算的栅格：地图建模与仿真环境搭建

2.1 为什么不能直接用A*：先分清已知地图和未知迷宫

很多初学者拿到题目第一反应是“A*几行代码不就完了”，这是把两类问题混在一起了：已知地图的最短路径求解，和未知迷宫的在线探索。前者是静态规划，给一张完整地图，求从起点到终点的最短路径；后者要求机器人一边感知一边决策，走错了还要能退回来。

做课程设计时，这类题目通常默认是后者：小车不知道全局地图，只有一圈测距传感器。这时候核心不是求最优路径，而是怎么在“看不到全图”的情况下完成探索、避障和回溯。如果把整张迷宫提前读进内存再用A*全局规划，演示效果会很漂亮，但答辩时一旦被问到“传感器数据在哪里进入决策”就容易露馅。所以开始写代码之前，先把问题边界画清楚：你做的是离线规划，还是在线探索？这决定了后面所有模块怎么拆。

2.2 用二维栅格建图：地图文件读出起点、终点与障碍

无论是仿真还是真机，第一步都是把迷宫抽象成二维栅格。墙用1表示，可通行区域用0表示，这样一个迷宫就是一张二维数组。这里我用一个很实用的约定：用文本文件存地图，#代表墙，空格代表通道。读取时按行扫描，第一行是地图顶部。

import numpy as np def load_maze(path): # 每行代表一行栅格，#为墙，空白为可通行区域 with open(path) as f: lines = [line.strip() for line in f if line.strip()] if not lines: raise ValueError("地图文件为空") grid = np.array([[1 if ch == "#" else 0 for ch in line] for line in lines]) free_cells = np.argwhere(grid == 0) if len(free_cells) < 2: raise ValueError("可通行格少于两个，无法确定起终点") start = tuple(free_cells[0]) # 左上角第一个可通行格 goal = tuple(free_cells[-1]) # 右下角最后一个可通行格 return grid, start, goal

这段代码做了三件事：读取文本、把字符映射成0/1矩阵、自动找起点终点。2.3节里会看到，后面传感器扫线和A*都要用同一个grid，所以地图读出来之后不要再手动改数组。

这里有两个关键参数需要注意。第一，np.argwhere返回的是(行, 列)索引，行对应y方向，列对应x方向，写坐标转换函数时最容易在这里翻车。第二，起点和终点用的是“第一个可通行格”和“最后一个可通行格”，如果地图文件里有明确的S和G标记，也可以单独解析；自动取首尾的好处是写测试地图时省事，坏处是没有S/G语义时容易选错入口。

2.3 给机器人加一只“探测眼”：简化测距传感器的建模

仿真里最常见的传感器模型是“扫线测距”：从机器人位置向某个角度发射一条射线，碰到墙就返回距离。这比模拟真实激光雷达简单得多，也足够模拟出声呐、红外传感器的效果。代码可以这样写。

import math MAX_RANGE = 60 # 最大探测距离，单位：栅格数 def sensor_scan(grid, x, y, yaw, angles_deg): distances = {} for ang in angles_deg: theta = yaw + math.radians(ang) for r in range(1, MAX_RANGE + 1): # 注意：gx对应列索引，gy对应行索引 gx = int(round(x + r * math.cos(theta))) gy = int(round(y + r * math.sin(theta))) if not (0 <= gy < grid.shape[0] and 0 <= gx < grid.shape[1]): distances[ang] = r break if grid[gy, gx] == 1: distances[ang] = r break else: distances[ang] = MAX_RANGE return distances

这里的实现是“逐步走格子”而不是求射线与网格的交点，计算量稍大但非常直观，迷宫行数在50以内时性能差距可以忽略。angles_deg一般是[-90, -45, 0, 45, 90]这样的列表，用来模拟左右和前后的探测角度。MAX_RANGE是一个容易被忽略的参数，如果你的目标是资源受限的小车，传感器量程就是真实量程，模拟里设得太大反而掩盖了“转弯时探测不到远处墙”的盲区。

更讲究的做法是用Bresenham直线扫描，或者用几何库直接求射线与线段的交点。但在项目初期，步进采样完全够用，先把整条链路跑通再优化性能不迟。

2.4 白盒仿真与黑盒决策：仿真循环里要暴露哪些量

自动走迷宫项目有两种常见跑法：纯Python写一个仿真循环，或者接ROS2这样的机器人平台做仿真。不管哪种，主循环的结构都差不多：初始化位姿、循环里采集传感器数据、调用决策模块、更新位姿、渲染地图。

我建议开发早期把决策函数当“黑盒”来调，只给它传感器输入和上一步动作，方便隔离问题。但仿真循环本身必须是“白盒”，要把机器人真实位置、航向角、每条决策后的误差全部暴露出来。否则等真机阶段位姿漂移到无法收场时，你连漂移是从哪一步开始的都不知道。

一个实用技巧是：每次决策后打印一行调试信息，包含动作、传感器读数、当前位姿、误差值。跑完一次迷宫后保留成日志文件，后续调PID或者改进探索策略时，这行日志就是唯一的后悔药。不要小看这个习惯，它能把几小时的调参时间压缩到十几分钟。

3. 迷宫寻路算法选型：BFS、A*、墙跟随与Tremaux的适用边界

3.1 已知地图求最短路径：A*的栅格实现与启发函数选择

在已经构建好栅格地图的场景下，A是内存和计算量权衡得比较好的选择。迷宫规模不大时BFS也能求最短路径，但从扩展性角度看A更可控。下面是一段最小可运行的A*实现，用堆优化过，迷宫十几万格也不会卡。

import heapq def heuristic(a, b): # 曼哈顿距离，适合只允许上下左右移动的栅格 return abs(a[0] - b[0]) + abs(a[1] - b[1]) def astar(grid, start, goal): rows, cols = grid.shape open_heap = [(0, start)] came_from = {} g_score = {start: 0} f_score = {start: heuristic(start, goal)} while open_heap: _, cur = heapq.heappop(open_heap) if cur == goal: path = [cur] while cur in came_from: cur = came_from[cur] path.append(cur) return path[::-1] for dx, dy in ((1, 0), (-1, 0), (0, 1), (0, -1)): nb = (cur[0] + dx, cur[1] + dy) if not (0 <= nb[0] < rows and 0 <= nb[1] < cols): continue if grid[nb[0], nb[1]] == 1: continue tentative = g_score[cur] + 1 if tentative < g_score.get(nb, float('inf')): came_from[nb] = cur g_score[nb] = tentative f_score[nb] = tentative + heuristic(nb, goal) heapq.heappush(open_heap, (f_score[nb], nb)) return []

这段代码里heuristic用的是曼哈顿距离，因为栅格迷宫只允许四方向移动时，曼哈顿距离永远不会高估实际代价，A*能找到最优路径。如果你改成八方向移动，得用欧氏距离，并且还要处理“斜穿墙角”的判定，否则路径会从墙的尖角切过去。

把这段代码和BFS、Dijkstra放在一起对比，能更清楚为什么选A*。

迷宫题目里每走一步代价相同，所以BFS和A的结果一样；但A的扩展节点少，路径长时快很多。

3.2 未知迷宫探索：墙跟随状态机与Tremaux回溯规则

如果题目要求机器人事先不知道地图，全局规划就用不了。经典的在线探索策略是墙跟随：右手始终贴着墙，遇到死路就绕。这个策略实现极其简单，但正确性依赖一个前提——迷宫是“简单连通”结构，所有墙连成一片，没有孤立的墙环。

墙跟随的决策其实是一个状态机，代码可以这样写。

def wall_follow_action(left_dist, right_dist, front_dist): # 前方空间充足，优先直行 if front_dist > FORWARD_SPACE: return "go_straight" # 右手边空间不足，说明右侧有墙，保持贴墙 if right_dist < WALL_DISTANCE: return "turn_left" # 前方没路，向右转找路 return "turn_right"

FORWARD_SPACE和WALL_DISTANCE要根据机器人的物理尺寸和转弯半径设。比如小车宽度占2个栅格，转弯半径占3个栅格时，通道宽度小于5格就得禁止强行转弯。很多仿真里看起来能过的弯，真机上就是过不去，问题就出在这两个阈值设得太大或太小。

Tremaux算法是比墙跟随更稳的未知迷宫方案：在每个路口记录每条支路被访问的次数，优先走一次都没走过的路；如果所有路都走过，就选只走过一次的路返回。这等于把探索过程变成深度优先搜索，天然不容易死循环。但它需要机器人在迷宫里能稳定识别“我到了哪个路口”，这又回到定位问题。仿真里可以直接用栅格坐标做标记，真机上就要靠里程计或者视觉路标辅助。

3.3 为什么规划出的路径不能直接当指令执行

很多人把A*算出来的路径直接转成“往前走几步、左转、再走几步”这样的指令序列，仿真里看着没事，一换仿真精度更高或换真机就穿墙。原因是规划模块输出的是理想轨迹，不包含执行误差。

常见的工程做法是把路径转成路径点列表，然后每一帧计算“当前位置到目标路径点”的航向偏差和距离偏差，用这个偏差去驱动转向控制器。也就是说，规划只负责给目标点，控制负责把车带到目标点。这两件事拆开之后，换地图、换底盘、换传感器都不用推翻重写，这也是自动走迷宫这类源码工程最值得学习的模块划分方式。别把规划、控制、决策全揉进一个大循环，后面排查问题会很痛苦。

4. 走不直就赢不了：差速运动模型与转向PID的工程参数

4.1 差速轮的运动学模型：把左右轮转速变成线速度与角速度

两轮差速底盘是迷宫小车最常见的构型。左右轮各自带编码器，根据两轮速度可以推算出机器人的线速度和角速度。下面的函数输入当前位姿和左右轮速度，输出一小段时间后的位姿。

import math def diff_drive_step(x, y, yaw, v_left, v_right, wheel_base, dt): # 线速度是两轮平均值 v = (v_left + v_right) / 2.0 # 角速度等于两轮差除以轮距 w = (v_right - v_left) / wheel_base if abs(w) < 1e-6: # 近似直线运动 x += v * dt * math.cos(yaw) y += v * dt * math.sin(yaw) else: # 绕瞬时旋转中心做圆弧运动 radius = v / w dx = -radius * math.sin(yaw) + radius * math.sin(yaw + w * dt) dy = radius * math.cos(yaw) - radius * math.cos(yaw + w * dt) x += dx y += dy yaw += w * dt return x, y, yaw

注意两个参数：wheel_base是左右轮间距，这个值直接影响角速度计算，量错一点弯道就会产生明显偏差；dt是控制周期，一般取0.01到0.05秒。控制周期太长，仿真里的运动轨迹会明显失真；太短，键盘显示和日志量会变大，排错反而麻烦。

这个运动模型同时是里程计的基础。每帧调用一次diff_drive_step，累积出来的位置就是机器人心目中的“我在哪”。后面谈漂移问题时，你会看到这个模型越精确，里程计越可靠。

4.2 转向PID怎么调：位置式PID的原型与四个起始参数

让机器人沿着路径走，本质是控制航向。用PID控制器来调节角速度是标准做法。输入是目标航向与当前航向的误差，输出是角速度或者转向角。一个最常见的坑是：Kp调大了，小车在直道上左右摆动；调小了，过弯道反应慢。先给一个基础实现。

class PID: def __init__(self, kp, ki, kd, integral_limit=0.5): self.kp = kp self.ki = ki self.kd = kd self.integral_limit = integral_limit self.last_error = 0.0 self.integral = 0.0 def compute(self, error, dt): # 积分项必须限幅，防止长直道上积分饱和 self.integral += error * dt if self.integral > self.integral_limit: self.integral = self.integral_limit elif self.integral < -self.integral_limit: self.integral = -self.integral_limit derivative = (error - self.last_error) / dt if dt > 0 else 0.0 self.last_error = error return self.kp * error + self.ki * self.integral + self.kd * derivative pid_yaw = PID(kp=2.0, ki=0.05, kd=0.8, integral_limit=0.5)

参数起始值一般从下面这张表开始调，而不是凭感觉填。

调参顺序建议是：先把Ki和Kd设成0，只调Kp，直到小车直道走起来有轻微震荡；然后加Kd把震荡压住；最后加一点点Ki消除静态误差。这个顺序能把“玄学调参”变成可追踪的过程。

4.3 里程计漂移与传感器延迟：直线不直的真正原因

仿真环境里如果完全不模拟噪声，PID很容易调到很理想；换到真机上就会露馅。轮子打滑、地毯摩擦系数变化、编码器量化误差，都会让里程计位置越来越不准。所以仿真里建议给传感器读数加一点高斯噪声，让决策模块从一开始就适应不完美的输入。

还有一个容易被忽略的问题：传感器读数和转向执行之间有延迟。声呐测距一次要几十毫秒，PID计算又要时间，等车头已经偏了10度才拿到前一帧的读数，自然走不直。处理办法是降低控制周期，把PID计算频率提高到传感器数据刷新频率的2倍以上，并且在延迟大的场景下用Kd而非继续加Kp。

这个话题再往上走就是基于卡尔曼滤波的传感器融合，或者干脆做一个简化版的SLAM机器人位姿估计，但迷宫项目一般不需要走到那一步。先保证里程计漂移可控，再谈更高阶的融合。

5. 自动走迷宫高频翻车现场：5个排查方法

5.1 传感器方向装反，机器人越躲越贴墙

现象：左侧墙距离小于阈值，明明应该向右微调，车却向左靠，最后直接贴上墙。

原因：传感器扫线的角度定义和转向方向不一致。比如扫线时把90度定义成右侧，但决策代码里把负角度误当成右侧，导致“右转避让”实际作用下的是左侧。这类问题在纯仿真里很难发现，因为地图和传感器常常是一起写的。

解决：做一个方向校验脚本。让机器人停在墙边，逐个角度扫线并打印读数，确认0度是车头正前方，左右角度读数对称。发现反了，把angles_deg列表整体取反，或者把PID输出符号反转。先校验方向再调参数，能省掉大量无效调参时间。

5.2 墙跟随在环状迷宫里死循环

现象：跑了十几分钟，轨迹一直重复经过同一片区域，小车绕着一个圈来回转。

原因：迷宫不是简单连通结构，存在独立的墙环或孤岛区域。右手法则在这种情况下会进入环路，因为算法没有“这里我来过”的记忆。

解决：把墙跟随升级成Tremaux或带访问计数器的DFS。最简单的方式是在每个路口格子维护一个访问次数，当所有可选方向的访问次数都不小于1时，强制选择访问次数最少的方向。这样会把探索行为变成深度优先搜索，环路也能被回溯机制打破。如果连“识别路口”都做不到，先加一个路口的标记机制再谈避免死循环。

5.3 PID积分饱和，长走廊里越走越蛇形

现象：在长直走廊里车头左右摆动幅度逐渐变大，最后撞墙。

原因：误差一直保持同一个符号，积分项持续累积，输出限幅后积分还在堆，导致转向打过头。这是PID在迷宫场景里最典型的翻车现场。

解决：给积分项加限幅，即代码里的integral_limit。更稳的做法是只在误差绝对值小于某个阈值时才允许积分累积，比如|error|小于5度才积分，误差大了先靠比例项把方向拉回来。还有一点经验：长直道里Kd的作用远大于Ki，宁可Ki给很小，也不要用积分去压长距离的残留误差。

5.4 栅格坐标与数组下标反了，路径整条穿墙

现象：地图读出来没错，A*算出来的路径却从墙里穿过。

原因：数组索引是grid[行, 列]，而绘图坐标通常习惯用(x, y)，两者混用时会整体转置。转置地图后视觉上完全正常，但实际通行判定全部错位。

解决：地图类里只暴露to_grid(x, y)和from_grid(row, col)两个转换函数，业务代码禁止直接操作数组下标。写完之后用一个简单脚本验证：把A*的路径点画到原始文本地图上，肉眼逐点核对，这一步能挡住90%的坐标类bug。

5.5 规划路径完美但真机走不出来：反馈闭环缺失

现象：仿真里跑得好好的，一接真实环境或高仿真环境就撞墙，而且每次撞的位置不一样。

原因：路径规划是开环的，代码把A*路径转成固定速度和转向序列，没有任何传感器反馈参与修正。仿真环境越理想，这个问题暴露越晚。

解决：路径规划结果拆成路径点，控制层每个周期计算“当前航向与目标路径点航向”的偏差，把它送入PID。等于规划只负责指路，控制负责执行，传感器负责修正。加上这个反馈闭环后，同样的路径在噪声更大的环境下也能走完。

6. 把迷宫成绩再压一截：两次跑图、曲线减速与离线验证

自动走迷宫项目的评分通常看两件事：能不能走出去，以及走出去用了多长时间。想压缩时间，最实用的做法是“第一次探索，第二次竞速”。第一遍跑的时候把路口的可行方向、距离、转向耗时全记下来，第二遍直接沿着记忆的最优方向跑，不再现场决策。这比让算法在线完美决策要简单可靠，也是很多迷宫比赛的真实策略。

竞速时速度不是恒定的，可以用一个很简单的分段限速函数。

def target_speed(dist_to_goal, min_speed=0.4, max_speed=1.0): # 距离目标点越近，速度越慢，保证转弯不失控 if dist_to_goal < 0.3: return min_speed return max(min_speed, min(max_speed, dist_to_goal * 0.5))

思路是：离目标路径点远时全速跑，离得近时提前减速。在迷宫拐角前1.5个栅格开始减速，比到了弯道再打方向盘稳定得多。继续优化时，可以把每次转向耗时记进日志，找出耗时最多的几个路口，单独调它们的减速起点。

最后是验证方法。用随机迷宫生成器生成50个不同地图，跑一遍统计成功率、平均耗时、最大耗时，比反复手测同一张图有说服力得多。我自己的经验是：第一次把所有模块写在一个while True里，日志乱成一团，排查一个坐标偏移问题用了两天；后来把感知、规划、控制拆成独立模块，随便一个变量出错都能按日志精确定位。代码组织越早清晰，后面调参越轻松。希望帮到你。

本文还有配套的精品资源，点击获取