1. 项目缘起与整体设计思路

1.1 为什么选择“走迷宫”作为Java入门实战项目

很多刚开始学Java的朋友，学完语法之后都会卡在一个尴尬的位置：语法都懂，但不知道能拿它做什么。看教程写个“Hello World”太无聊，直接上手做管理系统又太复杂，中间缺一个难度适中、能立刻看到效果、还能把核心知识点串起来的小项目。走迷宫这个小游戏，恰好就卡在这个甜点位上。

它不像贪吃蛇那样需要处理连续运动和时间步长，也不像五子棋那样涉及复杂的胜负判定和AI搜索。迷宫的核心逻辑非常干净：有一个二维网格，有墙有路，有一个起点一个终点，玩家用键盘控制角色移动，碰到墙走不动，走到终点就通关。就这么简单。但简单不代表简陋，它背后能牵扯出来的东西其实相当多——二维数组、坐标系统、键盘事件监听、Swing绘图、碰撞检测、路径搜索算法，甚至还能扩展到自动寻路和关卡生成。

我个人的经验是，一个新手如果能把走迷宫从零到一完整写出来，他对Java基础、面向对象、事件驱动编程的理解会有一个质的飞跃。因为这个小项目逼着你把“数据怎么存”“画面怎么画”“输入怎么接”“逻辑怎么判”这四个问题全部想清楚，而这四个问题恰恰是所有交互式程序的骨架。

1.2 技术选型：为什么用Swing而不是JavaFX

做Java桌面小游戏，绕不开的一个选择就是用Swing还是JavaFX。网上很多新教程会推荐JavaFX，说它更现代、支持CSS、控件更漂亮。这话没错，但对于走迷宫这个项目，我依然建议用Swing，原因有三。

第一，Swing是JDK自带的，不需要额外引入任何依赖。你打开IDE新建一个项目，直接就能用JFrame、JPanel、Graphics这些类，不用配Maven依赖，不用管模块化配置。对于新手来说，少一个环节就少一堆报错。

第二，Swing的绘图模型非常直白。你重写paintComponent(Graphics g)方法，然后用g.fillRect()画墙、g.fillOval()画玩家，所见即所得。JavaFX的Canvas虽然也能画，但它的场景图概念对新手来说多了一层抽象。

第三，也是最重要的一点，Swing的资料足够多、足够老。你遇到任何问题，搜索“Swing 键盘监听”“Swing 重绘”都能找到大量可用的答案。JavaFX的版本兼容性问题反而容易让新手踩坑。

当然，Swing确实丑，默认的按钮和窗口风格停留在上个时代。但走迷宫这个项目里，我们几乎不用标准控件，所有画面都是自己用Graphics画出来的，所以Swing的“丑”根本不影响最终效果。你完全可以用代码画出很清爽的迷宫画面。

1.3 整体架构：三层分离的设计

虽然是个小游戏，但我建议从一开始就养成分层的好习惯。走迷宫可以拆成三个层次：

• 数据层：用一个二维整型数组int[][] maze来存储迷宫地图。0表示通路，1表示墙，2表示终点。这个数组就是整个游戏的“真相来源”，所有逻辑判断都基于它。
• 逻辑层：处理玩家的坐标、移动请求、碰撞检测、胜利判定。这一层不关心画面怎么画，只关心数据怎么变。
• 表现层：继承JPanel，重写paintComponent方法，根据数据层的数组和玩家坐标，把画面绘制出来。同时注册键盘监听，把按键事件传递给逻辑层。

这样分层的好处是，如果你想换一套皮肤，只改表现层就行；如果你想换一种迷宫生成算法，只改数据层就行。各层之间通过明确的接口通信，不会牵一发而动全身。

注意：新手最容易犯的错误就是把所有代码都塞进一个类里，paintComponent里既画图又改数据，键盘监听里既移动又判定胜利。这样写出来的代码超过两百行就会变得难以维护，加一个新功能就到处改。分层不是过度设计，而是让你后面少受罪。

2. 核心细节解析与实操要点

2.1 迷宫地图的表示：二维数组的门道

迷宫地图用二维数组表示，这个大家都知道。但具体怎么定义，里面有不少细节值得说。

我一般用int[][]而不是boolean[][]，因为整型能表达更多状态。0是通路，1是墙，2是终点，后面如果加传送门、陷阱、钥匙，直接加3、4、5就行。如果用布尔数组，只有true和false两种状态，扩展起来就得换数据结构。

数组的维度选择也有讲究。我建议用maze[row][col]的形式，也就是第一个下标是行（对应y轴），第二个下标是列（对应x轴）。这跟屏幕坐标系的直觉一致：往下走行号增加，往右走列号增加。如果你反过来用maze[x][y]，画图的时候就得时刻提醒自己转置，很容易搞混。

地图数据我通常直接硬编码在代码里，用字符串数组来初始化，可读性最好。比如：

String[] mapData = { "1111111111", "1000000001", "1011111101", "1010000101", "1010110101", "1000120001", "1111111111" };

每一行是一个字符串，1是墙，0是路，2是终点。然后用一个双重循环把它转成int[][]。这样做的好处是你一眼就能看出迷宫长什么样，改地图直接改字符串就行，不用去数数组下标。

实操心得：地图字符串的每一行长度必须完全一致，否则转数组的时候会越界。我习惯在转换之前先检查所有行的长度是否等于第一行的长度，不等就直接抛异常，把问题扼杀在初始化阶段。

2.2 玩家移动与碰撞检测的核心逻辑

玩家移动看起来简单，其实藏着几个容易翻车的点。

首先，玩家坐标我用两个int变量playerRow和playerCol来表示，而不是用像素坐标。为什么？因为迷宫是格子化的，玩家永远在一个格子里，用格子坐标做碰撞检测最直接。如果我用像素坐标，每次移动还要做像素到格子的换算，多此一举。

移动逻辑是这样的：按下方向键后，先计算出目标格子的坐标。比如按上键，目标就是(playerRow - 1, playerCol)。然后检查这个目标格子是不是合法的。合法的条件有两个：一是在数组范围内，不能越界；二是maze[targetRow][targetCol] != 1，也就是不能是墙。

两个条件都满足，才更新playerRow和playerCol，然后调用repaint()触发重绘。如果目标格子是墙或者越界，就什么都不做，玩家原地不动。

这里有个细节：边界检查一定要在访问数组之前做。如果你先写if (maze[targetRow][targetCol] != 1)，当targetRow是-1或者等于数组长度时，直接抛ArrayIndexOutOfBoundsException。正确的顺序是先检查targetRow >= 0 && targetRow < maze.length && targetCol >= 0 && targetCol < maze[0].length，再检查是不是墙。

int targetRow = playerRow + dRow; int targetCol = playerCol + dCol; if (targetRow >= 0 && targetRow < maze.length && targetCol >= 0 && targetCol < maze[0].length && maze[targetRow][targetCol] != 1) { playerRow = targetRow; playerCol = targetCol; repaint(); }

这段代码我建议你背下来，因为几乎所有格子类游戏的移动逻辑都是这个套路，换汤不换药。

2.3 键盘监听的正确姿势

Swing里处理键盘事件，新手最常踩的坑就是焦点问题。你写了KeyListener，代码看起来没问题，但按键盘就是没反应。十有八九是因为面板没有获得焦点。

解决方法是：在面板初始化的时候调用setFocusable(true)，然后调用requestFocusInWindow()。这两个调用缺一不可。setFocusable(true)让面板可以被聚焦，requestFocusInWindow()主动请求焦点。如果只写前者，面板虽然可以聚焦，但默认焦点可能在别的地方，键盘事件还是传不过来。

另一个坑是，KeyListener必须注册在真正处理事件的面板上，而不是注册在JFrame上。因为JFrame的焦点管理跟JPanel不一样，注册在JFrame上经常收不到事件。我的习惯是让游戏面板自己实现KeyListener接口，然后在构造函数里addKeyListener(this)。

还有一点，方向键在Swing里默认会被用来做焦点遍历，也就是说按方向键可能会把焦点从一个组件移到另一个组件，而不是触发你的keyPressed。要阻止这个行为，可以在面板上调用setFocusTraversalKeysEnabled(false)。这一行代码能省掉你半小时的调试时间。

常见问题：为什么我按了方向键，玩家移动了，但画面没更新？检查你有没有在移动之后调用repaint()。Swing不会自动重绘，你必须显式告诉它“画面脏了，重新画一下”。

3. 实操过程与核心环节实现

3.1 项目骨架搭建：从零开始建三个类

我建议把项目拆成三个类：MazeApp（入口）、GamePanel（游戏面板）、MazeMap（地图数据管理）。当然你也可以合并成一个类，但分开写更清晰，后面扩展也方便。

MazeApp的职责很简单，就是创建窗口、设置大小、添加游戏面板、设置关闭行为。代码大概长这样：

public class MazeApp { public static void main(String[] args) { JFrame frame = new JFrame("走迷宫"); frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); frame.setResizable(false); GamePanel panel = new GamePanel(); frame.add(panel); frame.pack(); frame.setLocationRelativeTo(null); frame.setVisible(true); panel.requestFocusInWindow(); } }

注意frame.pack()会按照面板的首选大小来调整窗口，所以GamePanel里要重写getPreferredSize()，返回迷宫的像素尺寸。比如每个格子30像素，迷宫10列7行，那首选大小就是300x210。

MazeMap类负责持有int[][]数组，提供isWall(row, col)、isGoal(row, col)这些查询方法。把地图数据单独抽出来，后面你想换地图、加地图，都只改这一个类。

GamePanel是核心，继承JPanel并实现KeyListener。它持有MazeMap对象和玩家坐标，在paintComponent里画迷宫和玩家，在keyPressed里处理移动。

3.2 绘制迷宫：用循环把数组变成画面

paintComponent方法是整个游戏视觉呈现的核心。它的逻辑很直接：遍历二维数组，遇到1画墙，遇到0画地板，遇到2画终点，最后在玩家坐标处画一个圆形代表玩家。

@Override protected void paintComponent(Graphics g) { super.paintComponent(g); for (int row = 0; row < map.getRows(); row++) { for (int col = 0; col < map.getCols(); col++) { int x = col * CELL_SIZE; int y = row * CELL_SIZE; if (map.isWall(row, col)) { g.setColor(new Color(60, 60, 60)); g.fillRect(x, y, CELL_SIZE, CELL_SIZE); } else if (map.isGoal(row, col)) { g.setColor(new Color(255, 215, 0)); g.fillRect(x, y, CELL_SIZE, CELL_SIZE); } else { g.setColor(new Color(240, 240, 240)); g.fillRect(x, y, CELL_SIZE, CELL_SIZE); } g.setColor(new Color(200, 200, 200)); g.drawRect(x, y, CELL_SIZE, CELL_SIZE); } } // 画玩家 g.setColor(new Color(30, 144, 255)); int px = playerCol * CELL_SIZE + CELL_SIZE / 6; int py = playerRow * CELL_SIZE + CELL_SIZE / 6; g.fillOval(px, py, CELL_SIZE * 2 / 3, CELL_SIZE * 2 / 3); }

这里有几个细节值得说。第一，super.paintComponent(g)必须调用，否则背景可能不会正确清除，画面会出现残影。第二，drawRect画格子边框，能让迷宫看起来更规整，不然一片色块容易糊在一起。第三，玩家圆形留了六分之一格子的边距，这样玩家不会贴着墙，视觉上更舒服。

颜色选择上，墙用深灰、地板用浅灰、终点用金色、玩家用蓝色，对比度足够，长时间看也不累。你可以根据自己的审美调，但建议墙和地板的明度差要大一些，不然看不清路。

3.3 胜利判定与游戏状态管理

胜利判定很简单：玩家移动之后，检查当前格子是不是终点。如果是，就设置一个gameWon标志为true，然后在paintComponent里根据这个标志画胜利提示。

if (map.isGoal(playerRow, playerCol)) { gameWon = true; }

gameWon为true之后，keyPressed里就直接return，不再处理移动，防止玩家继续走。同时画面上用大字显示“通关”之类的提示。

if (gameWon) { g.setColor(new Color(0, 128, 0)); g.setFont(new Font("SansSerif", Font.BOLD, 36)); g.drawString("通关！", 80, 120); }

如果你想让游戏更完整，可以加一个步数计数器，每移动一次加一，通关时显示总步数。这个改动很小，但能让玩家有目标感，愿意再玩一次看能不能用更少步数通关。

实操心得：gameWon标志最好用volatile修饰，虽然在这个单线程Swing模型里不是必须的，但养成习惯没坏处。另外，胜利之后如果你想支持重新开始，可以监听R键，重置玩家坐标和gameWon标志，然后repaint()。

3.4 从手动地图到自动生成：扩展思路

手动设计地图适合入门，但玩几次就腻了。你可以进一步实现自动生成迷宫，让每次打开游戏都是新地图。最经典的算法是深度优先搜索（DFS）回溯法，也叫递归回溯。

思路是这样的：先把整个地图填满墙，然后从起点开始，随机选择一个方向，如果那个方向隔一个格子的位置还是墙，就打通中间的墙，递归进去。这个过程会生成一个没有环的完美迷宫。

void carve(int row, int col) { maze[row][col] = 0; int[] dirs = {0, 1, 2, 3}; shuffle(dirs); for (int d : dirs) { int nr = row + dr[d] * 2; int nc = col + dc[d] * 2; if (inBounds(nr, nc) && maze[nr][nc] == 1) { maze[row + dr[d]][col + dc[d]] = 0; carve(nr, nc); } } }

这个算法生成的迷宫保证有解，而且路径唯一。如果你想要更复杂的迷宫，可以在此基础上随机打通一些额外的墙，制造多条路径。

自动生成迷宫的代码量不大，大概五六十行，但它能让你的项目从“练习”升级成“作品”。面试的时候拿出来展示，也比一个固定地图的走迷宫有说服力。

4. 常见问题与排查技巧实录

4.1 键盘没反应：焦点问题的系统排查

键盘没反应是Swing新手遇到的第一大问题。我整理了一个排查清单，按顺序检查基本都能解决。

我踩过最坑的一次是，requestFocusInWindow()在setVisible(true)之前调用了，结果焦点请求被忽略。后来改成在setVisible之后调用，问题立刻解决。这个顺序问题在文档里写得很隐蔽，但实际开发中非常常见。

4.2 画面闪烁与重绘性能问题

如果你的迷宫比较大，或者加了动画效果，可能会遇到画面闪烁。这是因为Swing默认的重绘机制会先用背景色填充整个面板，再画内容，两次绘制之间有个短暂的空窗。

解决方法是开启双缓冲。Swing的JPanel默认是双缓冲的，但如果你在paintComponent里做了复杂操作，可以显式确认isDoubleBuffered()返回true。如果返回false，可以在构造函数里调用setDoubleBuffered(true)。

另一个减少闪烁的技巧是，只重绘需要更新的区域，而不是整个面板。比如玩家移动时，只重绘旧位置和新位置两个格子。调用repaint(x, y, width, height)而不是无参的repaint()。不过对于走迷宫这种小项目，全屏重绘的性能开销可以忽略，没必要过早优化。

注意：不要在paintComponent里创建新的Font或Color对象。这些对象应该在构造函数里创建好，作为成员变量持有。paintComponent会被频繁调用，在里面创建对象会增加GC压力，虽然小项目感觉不明显，但养成好习惯很重要。

4.3 数组越界与逻辑错误的调试方法

走迷宫项目里最常见的运行时异常就是ArrayIndexOutOfBoundsException。除了前面说的边界检查顺序问题，还有一个容易忽略的地方：地图字符串转数组时，如果某一行长度不一致，转出来的数组就是锯齿状的，访问时就会越界。

我的做法是在MazeMap的构造函数里加一段校验：

int cols = mapData[0].length(); for (String line : mapData) { if (line.length() != cols) { throw new IllegalArgumentException("地图每行长度必须一致"); } }

这样问题会在初始化阶段就暴露出来，而不是等到玩家走到某个位置才崩溃。调试的时候，异常信息会直接告诉你哪一行长度不对，比运行时越界好定位得多。

对于逻辑错误，比如玩家穿墙、终点判定失效，我建议在keyPressed里加临时日志输出，打印玩家坐标和目标格子状态。用System.out.println就行，不用上调试器。看到坐标变化不符合预期，基本就能定位到是哪段逻辑写错了。

4.4 常见问题速查表

这张表里的问题，我几乎每一个都真实遇到过。尤其是“行列下标搞反”，在画图和逻辑之间来回切换时特别容易犯。我的建议是，在代码里统一命名规范：row永远对应y轴，col永远对应x轴，变量名不要用x和y来存格子坐标，避免混淆。

5. 从能跑到好用：体验优化与功能扩展

5.1 让操作更跟手：键盘重复与移动节奏

默认情况下，按住方向键不放，Swing会连续触发keyPressed，但触发频率取决于操作系统的键盘重复速率。这会导致一个问题：玩家按住右键，角色移动的速度忽快忽慢，不同电脑上体验不一致。

如果你想让移动节奏完全可控，可以改用keyPressed和keyReleased配合一个定时器。按下时记录方向，启动一个javax.swing.Timer，每隔固定毫秒数移动一格；松开时停止定时器。这样无论系统键盘重复速率如何，移动速度都是恒定的。

Timer moveTimer = new Timer(120, e -> { if (currentDirection != null) { tryMove(currentDirection); } });

120毫秒的间隔大概相当于每秒移动8格，手感比较适中。你可以根据格子大小调整，格子大就慢一点，格子小就快一点。

5.2 加一点视觉反馈：路径痕迹与步数显示

玩家走过的路径如果留下痕迹，会让迷宫看起来更有“探索感”。实现方法很简单：在MazeMap里再加一个boolean[][] visited数组，玩家每到一个格子就标记为true。paintComponent里画地板的时候，如果visited为true，就用稍微深一点的颜色。

步数显示就是在面板左上角用drawString画一行字，内容从stepCount变量来。每次成功移动stepCount++，通关时显示总步数。这两个小改动加起来不到二十行代码，但游戏的完成度会明显提升。

5.3 自动寻路：给迷宫加一个“提示”功能

如果你已经实现了迷宫生成，那自动寻路就是顺理成章的一步。最常用的算法是广度优先搜索（BFS），它能保证找到最短路径。

BFS的思路是：从起点开始，一层一层向外扩展，记录每个格子是从哪个格子来的。到达终点后，沿着记录反向回溯，就得到了一条最短路径。然后把这条路径用半透明颜色画出来，作为给玩家的提示。

// BFS核心逻辑示意 Queue<int[]> queue = new LinkedList<>(); queue.offer(new int[]{startRow, startCol}); int[][] prev = new int[rows][cols]; // ... 遍历直到找到终点 // 回溯prev数组得到路径

这个功能的技术含量比前面所有内容加起来都高，但它是你从“会写Java”到“会用算法解决问题”的一个标志。面试的时候，如果你能讲清楚BFS在迷宫寻路里的应用，比背八股文有说服力得多。

实操心得：BFS的队列用LinkedList或者ArrayDeque都行，但ArrayDeque性能更好。另外，prev数组初始化的时候全部填-1，表示“未访问”。回溯路径时如果发现prev是-1，说明路径断了，这种情况在合法迷宫生成算法下不会出现，但手动地图如果终点不可达就会遇到，需要处理。

5.4 关卡系统：从单地图到多地图

当你有了自动生成迷宫的能力，关卡系统就很容易做了。维护一个level变量，每通关一次就加一，然后重新生成一个更大的迷宫。迷宫大小可以跟关卡挂钩，比如size = 7 + level * 2，保证是奇数，这样DFS生成算法才能正常工作。

难度曲线可以通过调整迷宫大小和是否添加额外通路来控制。前期关卡小一点、路径唯一，后期关卡大一点、多几条岔路。这样玩家能感受到明显的进度感，而不是重复玩同一个东西。

6. 一些踩坑之后的个人体会

走迷宫这个项目，我从第一次写到后来反复重构，前后改过好几版。最大的体会是：先把核心跑通，再谈优化和扩展。我见过不少新手，一上来就想做自动寻路、做关卡系统、做漂亮的UI，结果核心的移动和碰撞还没调通，代码就写了一千多行，最后到处都是bug，自己也理不清了。

正确的节奏应该是：先让一个固定地图能显示出来，再让玩家能移动，再让碰撞检测生效，再让终点判定生效。这四步每一步都跑通了，再去加自动生成、加寻路、加关卡。每一步都是在前一步稳定的基础上叠加，这样出了问题你立刻知道是新加的那部分有问题，而不是在一堆代码里大海捞针。

另一个体会是，注释和命名比你想的重要。走迷宫的逻辑不复杂，但涉及坐标、方向、数组下标，很容易写着写着就糊涂了。我后来养成的习惯是，所有跟坐标相关的变量都带上row或col后缀，所有方向常量都用DIR_UP、DIR_DOWN这样的名字，而不是直接写0、1、2、3。这样过一个月再回来看代码，也能立刻看懂。

最后分享一个小技巧：如果你在调试碰撞检测，可以把maze数组直接打印到控制台，用#表示墙、.表示路、@表示玩家。每次移动后打印一次，你就能直观地看到玩家坐标和地图数据是否一致。这个方法比看图形界面调试快得多，尤其是在排查“为什么玩家能穿墙”这类问题时，一眼就能看出是坐标算错了还是判断条件写反了。

这个项目后续还可以往很多方向扩展，比如加入计时挑战、加入迷雾效果（只显示玩家周围一定范围）、加入音效反馈。但那是另一个话题了，先把基础版本写扎实，后面的扩展都是水到渠成的事。