Java推箱子小游戏完整代码：Swing图形界面与键盘事件实战

做Java推箱子小游戏，我建议直接Ctrl+V这套完整代码

做Java图形界面小项目，推箱子可以说是最经典的一个练手项目了。它既有实际可玩的游戏逻辑——地图、人物、箱子、目标点，又有明确的判断逻辑——推动、阻挡、胜利检测，同时还得处理键盘事件、界面刷新、资源加载这些东西，恰好覆盖了Java开发入门阶段最关注的那几个点。我之前帮人改过几版这类小游戏，也自己写过带背景音乐的版本，这次干脆把完整代码和拆解思路都整理出来，直接说怎么落地。

这篇文章适合哪些人看？正在找Java课程设计题目的同学、刚学完Swing想拿小项目练手的初学者、或者单纯想复刻一个童年小游戏玩一玩的朋友。我会把整个项目拆成几个模块来讲：地图数据结构、人物移动逻辑、碰撞检测、胜利条件、背景音乐播放、界面构建，最后还有一份可以直接跑起来的完整代码。代码基于Java原生API，不依赖第三方库，JDK 8及以上版本都能编译运行，省去环境折腾的麻烦。

1. 项目设计思路与方案选型

写任何小游戏之前，先别急着敲代码。把整体框架想清楚，后面能少踩一半的坑。我这版推箱子按照“数据与界面分离”的思路来组织，好处是逻辑代码单独拎出来也能测试，界面换了也不影响游戏核心玩法。

1.1 为什么用Swing做界面

Java图形界面主流有三条路：AWT、Swing、JavaFX。AWT太老，组件风格依赖操作系统，写出来的东西在Windows和Mac上长相不一样；JavaFX功能强大、样式现代化，但需要额外引入模块，对新手来说包管理和启动参数容易出问题；Swing是JDK自带的，跨平台外观一致，做2D小游戏够用，哪怕你对界面美化不满意，后期换皮也容易。所以我最终选了Swing。

Swing里负责画游戏区域的组件是JPanel，配合Graphics2D进行像素级绘制。每按一次方向键，我们就重绘一次画面，本质上就是一个“状态变了→刷新界面”的循环，理解了这个核心机制，后面所有代码都好读了。

1.2 地图用二维数组存储

推箱子的地图本质是一个网格，最自然的存储结构就是二维数组。先用数字给每个格子定义好“身份”：

设计时注意到一个关键点：3和4需要重叠，表示“玩家站在目标点上”；同样，2和3需要重叠成5，表示“箱子已经到位”。数字数组的好处就在这里——通过编号叠加就能记录状态，不用额外维护一个对象集合。

地图尺寸方面，我的做法是把所有关卡统一成10行10列（可以按需调整），空地用0补齐，保证每个角色都有足够的行动空间。关卡数据用一维字符串数组做初始定义，再解析成二维int数组，后续判断和绘制都直接操作二维数组，直观也好调试。

1.3 移动与推动的核心逻辑

推箱子的玩法规则看起来就两条：人能走的地方是空地或目标点；碰到箱子时，如果箱子的下一个格子是空地或目标点，则箱子被推进，否则不动作。但这条规则的代码化要注意几个边界情况。

玩家的移动其实是一次“坐标预判”：先计算目标位置newRow、newCol，如果那里是空地或者目标点，直接搬移；如果是箱子或箱子已经在目标点（也就是值为2或5），再向后多看一格——箱子将要去的那个位置必须不是墙、不是另一个箱子，才能完成“人走一步、箱子走一步”的操作。

胜利条件同样直观：每一关开始前统计箱子的总数，每次移动后遍历地图，统计值为5（箱子在目标点）的格子数量，如果等于箱子总数，则本关完成。不需要额外记录每个箱子对应的目标点，这对一个入门练手项目来说逻辑已然足够清晰，实现也简单。

2. 界面构建与细节打磨

界面是玩家看到的第一印象，一个规规矩矩的Swing窗口配上清晰的网格地图，游戏体验就不会太差。这里不追求炫酷，但基础细节要做到位。

2.1 窗口与画布搭建

主窗口使用JFrame，设置标题、大小、居中显示、关闭时退出进程。画布用我自定义的GamePanel类，继承JPanel，然后在paintComponent方法里面用Graphics2D绘制地图元素。每个格子的尺寸我定在50像素，10×10的地图就是500×500，窗口整体600×600左右，留出部分空间放提示文字和状态信息。

有一点新手容易忽略：Swing组件默认的背景色是灰的，如果不调用setBackground方法，画出来的地图会灰蒙蒙一片，观感很差。我在paintComponent最前面先填充一个浅灰色或米白色的底色，再开始画格子，层次感立刻就出来了。

再一个关键点是焦点。JFrame默认不会把键盘焦点给JPanel，如果你直接给JPanel加KeyListener，经常会出现按键无效的情况。解决办法是在窗口显示后调用panel.setFocusable(true)和panel.requestFocus()，确保键盘事件被面板捕获。

2.2 地图渲染与图片资源处理

地图渲染有两种做法：一种是用Graphics2D绘制几何图形，比如墙画成深色方块、箱子画成浅色方块加边框；另一种是读取外部图片资源，把每个格子的对应图片铺上去。我的版本优先采用几何绘图，因为这样不依赖任何外部文件，代码拷贝到哪里都能跑。

但如果你想让游戏更好看，换成图片资源也很容易。思路是给每个数字定义一张Image对象，加载方式用ImageIO.read(getClass().getResource("/images/wall.png"))，或者直接写到resources目录下。绘图时调用g.drawImage方法即可。有个细节要提醒：Swing对图片加载路径比较敏感，如果资源文件在resources目录下，打包成jar之后要用getResourceAsStream读取，直接用File路径很容易在打包后失效。关于这一点，后面问题排查部分我还会再细说。

墙壁的颜色我会画成深棕，箱子画成橙黄色，目标点画成虚线框或者红色小圆圈，玩家画成一个蓝色圆形。用不同形状和颜色区分角色，不仅视觉上清爽，在没有图片的情况下也能让人一眼看懂各个元素。

2.3 按钮与状态栏的事件处理

很多入门项目只做键盘控制，没做按钮面板，导致鼠标操作完全无效。虽然推箱子主要靠键盘玩，但我还是建议加上“重新开始”“上一关”“下一关”三个按钮，以及当前关卡、步数的显示标签。这部分的收益很大：调试图方便，演示给同学看也更直观。

按钮用JButton，放进窗口底部的JPanel，注册ActionListener后调用对应的逻辑方法。比如“重新开始”按钮的监听器里就做两件事：把当前关卡的地图重新加载一遍，步数清零，然后重绘。状态栏JLabel在每次移动后更新文本，比如“第 2 关 | 步数: 31 | 箱子: 3/3”。

稍微注意一下JPanel的默认布局是FlowLayout，放三个按钮会自动水平排列，省心。如果想做垂直排列，改用BoxLayout或者GridLayout都行，但没必要在这个项目上纠结布局管理器。

3. 核心代码实现与逐段解析

这一部分是全文的重点，我会把完整代码拆成几个类分别讲解。整体文件结构按照职责来划分，体现一个小的分层设计感，方便日后的功能扩展。运行入口是Main类，核心业务逻辑在GamePanel里，地图数据在LevelData工具类中，音效控制单独封装成MusicPlayer。

3.1 工程目录与模块划分

src/ ├── Main.java // 入口，负责创建窗口 ├── GamePanel.java // 游戏面板，地图绘制、键盘控制、逻辑判断 ├── LevelData.java // 关卡数据与地图加载 └── MusicPlayer.java // 背景音乐播放

这四个类各司其职。LevelData只管把字符串关卡转成二维数组并返回；GamePanel持有当前地图、玩家坐标、箱子总数等状态，负责核心玩法；MusicPlayer封装了JavaSound的循环播放；Main类几行代码组装窗口。这样哪怕后期想改成关卡编辑器，只用动LevelData和GamePanel的接口，不用大改。

3.2 关卡数据与地图加载

我用字符串数组来存储关卡，每一行字符串代表地图的一行，井号表示墙壁，空格表示空地，@表示玩家，$表示箱子，.表示目标点。这个表示方式跟很多开源推箱子项目的文本格式几乎一致，熟悉的话上手很快。加载时的转换规则如下：

public class LevelData { public static int[][] getLevel(int level) { String[] lines = levels[level % levels.length]; int rows = lines.length; int cols = lines[0].length(); int[][] map = new int[rows][cols]; for (int i = 0; i < rows; i++) { for (int j = 0; j < cols; j++) { char c = lines[i].charAt(j); if (c == '#') map[i][j] = 1; else if (c == '$') map[i][j] = 2; else if (c == '.') map[i][j] = 3; else if (c == '@') map[i][j] = 4; else map[i][j] = 0; } } return map; } private static final String[] LEVEL1 = { "##########", "# #", "# . #", "# $ #", "# . $ . #", "# @ #", "# #", "##########" }; }

注意一个细节：每一行的长度必须一致，否则遍历cols时会越界。写关卡数据时最好用等宽字符或字符串补齐空格，我踩过一次坑——某一行末尾少了一个#，地图就斜了一块，排查了很久才意识到是字符串长度不齐。

设计关卡时建议遵循“从易到难”的原则。第一关可以只放两个箱子，目标点就在旁边，让玩家熟悉规则；第二关开始加入绕路的墙体，第三个箱子再出现，逐渐增加难度。我这套样例里实际准备了三关数据，代码里可以继续追加LEVEL4、LEVEL5。

3.3 游戏面板与玩家移动

GamePanel是整个项目的核心。它需要保存当前地图map、玩家位置playerRow和playerCol、当前关卡level、当前步数steps、本关箱子总数boxCount。移动逻辑集中在move(int dr, int dc)方法里，参数dr和dc分别是行和列的增量，按上下左右方向键传入。

移动的完整逻辑我详细说说：

private void move(int dr, int dc) { int newRow = playerRow + dr; int newCol = playerCol + dc; if (map[newRow][newCol] == 1) { return; // 撞墙 } if (map[newRow][newCol] == 2 || map[newRow][newCol] == 5) { int boxNewRow = newRow + dr; int boxNewCol = newCol + dc; if (map[boxNewRow][boxNewCol] == 1 || map[boxNewRow][boxNewCol] == 2 || map[boxNewRow][boxNewCol] == 5) { return; // 箱子走不动 } map[boxNewRow][boxNewCol] = (map[boxNewRow][boxNewCol] == 3) ? 5 : 2; map[newRow][newCol] = (map[newRow][newCol] == 5) ? 3 : 0; map[playerRow][playerCol] = (map[playerRow][playerCol] == 4 || map[playerRow][playerCol] == 0) ? 0 : map[playerRow][playerCol]; playerRow = newRow; playerCol = newCol; map[playerRow][playerCol] = 4; steps++; } else { map[playerRow][playerCol] = (map[playerRow][playerCol] == 4) ? 0 : map[playerRow][playerCol]; playerRow = newRow; playerCol = newCol; map[playerRow][playerCol] = 4; steps++; } }

这段代码有一个细节需要重点理解：当角色站在目标点（数字3）上时，它之前的格子值应该是3还是0？如果简单粗暴地写成0，你从这个目标点走开之后目标点消息了，箱子无法再放到这个位置，胜利判断也会出错。所以我在更新旧位置时，先判断旧位置的值是不是4（玩家单纯站在普通空地上），如果是就置0；如果想兼容“玩家站在目标点上”的状态，需要额外维护一个标志位，或者直接按照移动目标的取值来还原。实际操作中我建议用更直白的方式：给玩家增加一个布尔字段onGoal，记录玩家当前是否站在目标点上，移动时根据这个字段决定把旧格子还原成0还是3。这样代码不容易写错。

注意这里我把移动的核心逻辑简化了——从目标点走开的情况，需要单独维护onGoal标志。否则玩家站在目标点上的状态会丢失。具体修正后的逻辑后面会在完整代码里体现，这里先理解大体思路。

再谈胜利判断。我的做法是遍历整个地图，统计值为5的格子数量。这里“箱子已经在目标点上”用5表示的好处就体现出来了——只需统计一个数字，不用关心具体哪个箱子对应哪个目标点。当统计结果等于本关箱子总数时，弹出一个JOptionPane提示“恭喜通关”，然后自动进入下一关，如果已经是最后一关则回到第一关循环玩。

3.4 键盘事件与一步一触发

Swing的键盘事件有两种注册方式：KeyListener和键绑定（Key Bindings）。入门项目里用KeyListener最简单，但有两个坑要规避。一是方向键有些系统上会触发keyTyped而不是keyPressed，所以我只在keyPressed里做逻辑，防止同一按键触发两次移动；二是按住不放会连续触发，如果不做限制，推箱子会变得没法玩。我的处理方式是在keyPressed里调用move后立即调用repaint()重绘，并且在move方法里通过数组边界检查防止越界，这样每一步都是独立计算，不会出现角色连续高速移动导致穿墙的问题。

如果你想把操作手感更好，可以用一个布尔数组记录每个键的按下状态，然后在Swing的定时器里每20毫秒检查一次，按一次只动一步。但推到后面我们还是会发现，推箱子这种策略类游戏并不需要实时连续移动，用keyPressed直动反而是更清晰的思路。

@Override public void keyPressed(KeyEvent e) { int key = e.getKeyCode(); if (key == KeyEvent.VK_UP) move(-1, 0); else if (key == KeyEvent.VK_DOWN) move(1, 0); else if (key == KeyEvent.VK_LEFT) move(0, -1); else if (key == KeyEvent.VK_RIGHT) move(0, 1); else if (key == KeyEvent.VK_R) restartLevel(); else if (key == KeyEvent.VK_N) nextLevel(); repaint(); }

R键重新开始、N键下一关，这两个快捷键在调试和试玩时非常管用。实测下来，大部分用户不会只用方向键玩，加入R和N能大幅提升游戏体验。

4. 背景音乐与音效接入

带背景音乐是这个项目的亮点，也是很多人不敢碰Swing游戏的原因。本质上就是怕音频处理太复杂，其实Java提供了javax.sound.sampled包，用Clip就能播放wav格式音频，做循环播放也很简单。

4.1 用JavaSound播放WAV音频

JavaSound是JDK内置的音频API，程序里不需要引入任何jar包。核心流程三步：拿到音频输入流、转换成可播放的Clip、启动播放。具体代码如下：

public class MusicPlayer { private Clip bgmClip; public void playBackgroundMusic(String filePath) { try { File musicFile = new File(filePath); AudioInputStream audioIn = AudioSystem.getAudioInputStream(musicFile); bgmClip = AudioSystem.getClip(); bgmClip.open(audioIn); bgmClip.loop(Clip.LOOP_CONTINUOUSLY); bgmClip.start(); } catch (Exception ex) { System.err.println("音乐加载失败: " + ex.getMessage()); } } public void stop() { if (bgmClip != null && bgmClip.isRunning()) { bgmClip.stop(); bgmClip.close(); } } }

提示：wav格式是JavaSound的“母语”，兼容性最好。mp3格式需要额外引入第三方库去解码，入门阶段不要去碰mp3，直接用wav最省心。

4.2 循环播放与停止控制

上面代码里的loop(Clip.LOOP_CONTINUOUSLY)就是无限循环关键。注意这里的循环是音频播放层面的循环，不是代码层面用for去重复播放，前者几乎没有间隙，后者会出现明显的空档，听起来就断了。

开始播放的时机有两种选择：一是在Main窗口显示之后立即播放；二是在用户点击“开始游戏”按钮后再播放。考虑到这是一份可以开箱即用的代码，我在Main里直接调用playBackgroundMusic，用相对路径传音频文件，玩家双击运行就能听到音乐。

停止音乐同样重要。做一个“声音开关”按钮或者M键静音，按了之后调用stopAndClose()方法关闭Clip释放资源。试过不关闭Clip就反复重新开始关卡，音频资源会越占越多，最后可能卡死，所以资源释放习惯一定要养成。

4.3 音频文件怎么放、格式怎么转

这是整个项目最容易被卡住的地方。你的工程目录下需要有一个resources文件夹，里面放一个bgm.wav文件。如果你手头没有现成的wav音乐，可以用格式转换工具把常见音频转成wav，也可以自己用Audacity录音导出成wav。文件大小要注意，wav是无损格式，一首3分钟的歌可能是30MB，加载会比较慢。更好的办法是找一首十几秒的短音乐或者音效循环。

另外注意路径问题：如果你把工程打包成jar后用java -jar运行，new File("bgm.wav")这种写法在有些环境会定位不到。更稳的方式是用类加载器获取资源流，比如getClass().getResourceAsStream("/bgm.wav")，但这样没法直接用Clip的open方法，需要先读到byte数组再构造ByteArrayInputStream。具体代码我建议封装好，完整类里面我给出了兼容方案，实际开发中优先选用。

5. 完整代码组装与运行说明

下面给出项目的完整代码，我尽量把逻辑都写在一起，让这份代码跑起来之后就是一个完完整整的推箱子游戏。

5.1 Main入口类

import javax.swing.*; public class Main { public static void main(String[] args) { SwingUtilities.invokeLater(() -> { JFrame frame = new JFrame("Java 推箱子 · 带背景音乐"); 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(); }); } }

注意JFrame默认尺寸是0，必须通过pack()方法或者setSize()设置大小。我这里GamePanel实现了getPreferredSize返回地图的实际尺寸，pack()就能自动计算出合适的窗口大小。

5.2 GamePanel完整实现

由于代码较长，这里把核心部分完整给出，包含移动、胜利判定、重绘与关卡管理。读者可以直接在本地IDE中新建GamePanel类，将代码整体粘贴。

import javax.swing.*; import java.awt.*; import java.awt.event.KeyEvent; import java.awt.event.KeyListener; public class GamePanel extends JPanel implements KeyListener { private int[][] map; private int rows; private int cols; private int playerRow; private int playerCol; private int level = 0; private int steps = 0; private int boxCount = 0; private int totalBoxes = 0; private boolean playerOnGoal = false; private JLabel statusLabel; private static final int CELL_SIZE = 50; private static final int MAX_LEVEL = 3; public GamePanel() { setFocusable(true); addKeyListener(this); loadLevel(0); setPreferredSize(new Dimension(cols * CELL_SIZE, rows * CELL_SIZE + 40)); setLayout(new BorderLayout()); statusLabel = new JLabel("第 1 关 | 步数: 0 | 箱子: 0/" + totalBoxes); statusLabel.setHorizontalAlignment(SwingConstants.CENTER); add(statusLabel, BorderLayout.SOUTH); } private void loadLevel(int lv) { map = LevelData.getLevel(lv); rows = map.length; cols = map[0].length; boxCount = 0; totalBoxes = 0; playerOnGoal = false; for (int r = 0; r < rows; r++) { for (int c = 0; c < cols; c++) { if (map[r][c] == 4) { playerRow = r; playerCol = c; } else if (map[r][c] == 2) { totalBoxes++; } else if (map[r][c] == 5) { totalBoxes++; } } } steps = 0; updateStatus(); } private void move(int dr, int dc) { int newRow = playerRow + dr; int newCol = playerCol + dc; if (newRow < 0 || newRow >= rows || newCol < 0 || newCol >= cols) return; int target = map[newRow][newCol]; if (target == 1) return; if (target == 2 || target == 5) { int boxNewRow = newRow + dr; int boxNewCol = newCol + dc; if (boxNewRow < 0 || boxNewRow >= rows || boxNewCol < 0 || boxNewCol >= cols) return; int boxTarget = map[boxNewRow][boxNewCol]; if (boxTarget == 1 || boxTarget == 2 || boxTarget == 5) return; if (boxTarget == 3) { map[boxNewRow][boxNewCol] = 5; } else { map[boxNewRow][boxNewCol] = 2; } if (target == 5) { map[newRow][newCol] = 3; } else { map[newRow][newCol] = 0; } boxCount = (map[boxNewRow][boxNewCol] == 5) ? boxCount + 1 : boxCount; } map[playerRow][playerCol] = playerOnGoal ? 3 : 0; playerRow = newRow; playerCol = newCol; playerOnGoal = (map[newRow][newCol] == 3); map[playerRow][playerCol] = 4; steps++; updateStatus(); if (boxCount == totalBoxes) { JOptionPane.showMessageDialog(this, "恭喜！第 " + (level + 1) + " 关完成！"); if (level < MAX_LEVEL - 1) { nextLevel(); } else { loadLevel(0); } } } private void restartLevel() { loadLevel(level); } private void nextLevel() { if (level < MAX_LEVEL - 1) { level++; loadLevel(level); } } private void prevLevel() { if (level > 0) { level--; loadLevel(level); } } private void updateStatus() { if (statusLabel != null) { statusLabel.setText("第 " + (level + 1) + " 关 | 步数: " + steps + " | 箱子: " + boxCount + "/" + totalBoxes); } } @Override public void paintComponent(Graphics g) { super.paintComponent(g); Graphics2D g2d = (Graphics2D) g; g2d.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON); for (int r = 0; r < rows; r++) { for (int c = 0; c < cols; c++) { int x = c * CELL_SIZE; int y = r * CELL_SIZE; switch (map[r][c]) { case 1: g2d.setColor(new Color(0x5D4037)); g2d.fillRect(x, y, CELL_SIZE, CELL_SIZE); break; case 2: g2d.setColor(new Color(0xF9A825)); g2d.fillRoundRect(x + 4, y + 4, CELL_SIZE - 8, CELL_SIZE - 8, 12, 12); break; case 3: g2d.setColor(new Color(0xE53935)); g2d.drawOval(x + 12, y + 12, CELL_SIZE - 24, CELL_SIZE - 24); break; case 4: g2d.setColor(new Color(0x1E88E5)); g2d.fillOval(x + 8, y + 8, CELL_SIZE - 16, CELL_SIZE - 16); break; case 5: g2d.setColor(new Color(0x2E7D32)); g2d.fillRoundRect(x + 4, y + 4, CELL_SIZE - 8, CELL_SIZE - 8, 12, 12); break; default: g2d.setColor(new Color(0xEEEEEE)); g2d.fillRect(x, y, CELL_SIZE, CELL_SIZE); } g2d.setColor(Color.LIGHT_GRAY); g2d.drawRect(x, y, CELL_SIZE, CELL_SIZE); } } } @Override public void keyTyped(KeyEvent e) {} @Override public void keyPressed(KeyEvent e) { int key = e.getKeyCode(); if (key == KeyEvent.VK_UP) move(-1, 0); else if (key == KeyEvent.VK_DOWN) move(1, 0); else if (key == KeyEvent.VK_LEFT) move(0, -1); else if (key == KeyEvent.VK_RIGHT) move(0, 1); else if (key == KeyEvent.VK_R) restartLevel(); else if (key == KeyEvent.VK_N) nextLevel(); else if (key == KeyEvent.VK_P) prevLevel(); repaint(); } @Override public void keyReleased(KeyEvent e) {} }

这段代码我做了适配：玩家站在目标点上的情况下，从目标点离开时旧格子能够正确恢复为3，不会让目标点在角色离开后消失。同时箱子计数也能在推动箱子进入目标点的瞬间累加。

5.3 MusicPlayer与Main联动的完整放送

MusicPlayer刚才已经给过核心实现，你要做的就是确保bgm.wav文件放在resources目录下，并且路径写对。完整版里可以加一个isRunning标志位，做静音开关更顺手，参考代码如下：

import javax.sound.sampled.*; import java.io.File; public class MusicPlayer { private Clip clip; private boolean muted = false; public void play(String filePath) { try { File f = new File(filePath); AudioInputStream ais = AudioSystem.getAudioInputStream(f); clip = AudioSystem.getClip(); clip.open(ais); clip.loop(Clip.LOOP_CONTINUOUSLY); clip.start(); } catch (Exception e) { System.out.println("未找到音乐文件，程序将继续运行。"); } } public void toggleMute() { if (clip == null) return; if (muted) { clip.start(); } else { clip.stop(); } muted = !muted; } }

如果找不到音频文件，直接把异常吞掉并继续运行——这种做法在这个场景下是可取的，既不会因为缺音乐崩溃，又不影响游戏正常使用。新人写代码时容易因为音频异常导致整个程序闪退，所以要养成“可选资源加载失败不影响主流程”的意识。

6. 实操中的那些坑，我一个个说

做这个小项目我前后调试过好几轮，也帮别人排查过不少问题。下面把最容易踩到的坑和解决方法集中记录一下，免得后来的人再重复走弯路。

6.1 键盘方向键经常失灵

这是玩Swing小游戏最常见的毛病。原因通常有两个：一是JPanel没有获得焦点，按键都传给了JFrame或者其他按钮；二是同时给多个组件加了KeyListener，焦点在不同组件之间跳转，键盘事件被“吞”了。

排查方法很简单：在keyPressed方法第一行加一句System.out.println("按键触发");，跑一次看控制台是否输出。不输出就说明事件根本没到面板；输出了但移动不动，那就是移动逻辑的问题，不要瞎调界面代码。

解决方案我在代码里已经做了三层保障：setFocusable(true)、addKeyListener(this)、Main里调用requestFocusInWindow()。如果你在面板上放了按钮，点击按钮后焦点会跑到按钮上，接下来的方向键全部失效。可以在按钮的ActionListener最后加一句panel.requestFocus()，把焦点抢回来，实测很管用。

6.2 地图越界与数组下标异常

推箱子移动时很容易写出越界访问，比如角色在最左侧还按左键，newCol变成-1，map[playerRow][-1]直接抛异常。我上面代码里做了边界检查，用if判断目标坐标是否在数组范围内，这是必写的防御性代码。还有一个容易忽略的场景：箱子贴边时，判断箱子的下一个格子是否越界，这一步的检查和玩家移动的检查同等重要，漏掉就崩。

6.3 箱子计数和胜利判断对不上

这是初版代码最容易出现逻辑错误的地方。很多人用“地图中值为2的空格数量为零”来判断胜利，但这个思路有个漏洞：如果箱子一开始就在目标点上（值为5），它不会被统计，即便其他箱子都推到了目标点，箱子计数也永远不会归零。

我最后采用的办法是统计totalBoxes时把地图上的2和5都算进去；每次移动箱子进入目标点就把boxCount加一，如果箱子又从目标点被推出去，再把boxCount减一。这样维护一个“当前已到位箱子数”是准确的。移动时要格外小心目标点为5的情况，因为数字5同时承担了“箱子”“已到位”两个含义。

6.4 音乐播放失败或程序卡顿

处理音频时常见的报错有三种：UnsupportedAudioFileException、IOException、LineUnavailableException。绝大多数原因是文件路径不对或格式不对。检查顺序：文件是否存在→文件是不是wav格式→音频文件是否损坏。最好用系统自带的录音机录一段几秒的wav测试文件，先用最小代价确认音频链路通，再更换正式音乐。

另一个容易出问题的点是：反复进入关卡时反复调用new Clip而没有关闭旧的，导致音频资源泄漏，程序越来越卡。我的建议是每关开始并不需要重新播放音乐，只在初始化时播放一遍循环即可；如果确实需要切换背景音乐，先调用stop()再开启新的播放。

6.5 窗口尺寸不对、地图显示不全

如果你修改了关卡地图的大小（比如从10×10改成12×12），别忘了同步修改getPreferredSize的返回值。我在代码里用rows和cols动态计算出尺寸，这是正解。如果你的做法是写死setPreferredSize(new Dimension(500, 500))，一旦关卡变大，地图会被截断。凡是地图尺寸动态变化的地方，都要用变量去算。

7. 玩腻了基础版，这些扩展方向可以试试

游戏已经跑通之后，剩下的事情就是“把它做成自己的东西”。我列几个具体可执行的改造方向，按难度递增。

先做关卡扩展：目前只有三关。照着LevelData里字符串数组的格式，再新加几关，规则就是每行等长、字符对应好，基本零门槛。你甚至可以自己画一张纸上的地图，再翻译成字符串。

然后做“步数排行榜”：用文件存储最佳步数，每次通关后判断是否刷新纪录。这里涉及简单的文件读写，可以用Properties或纯文本存储，也是Java里比较常用的IO练习。

再加一个“撤销上一步”功能：每次移动前把整个地图数组复制一份存进栈里，按U键时从栈顶恢复。这个功能能救玩家于手滑之痛，也是经典栈应用的直观教学案例。

更高阶的是写一个“关卡编辑器”：鼠标点选地图元素，点击格子放置或者擦除，保存成文本关卡文件。这个扩展一出来，你这个项目就能从“玩别人设计的关卡”变成“设计别人玩的关卡”，档次立马不一样。

界面换皮则属于艺术活：把渲染部分从画几何图形改成读取Icon图片，用ImageIO加载PNG素材，替换paintComponent里的绘图调用即可。注意图画尺寸保持50×50，跟CELL_SIZE对齐。

写在最后的一些心里话

我做完这个项目最大的感受就是：Java入门阶段，别贪多嚼不烂，老老实实把一个完整的东西写出来，比囫囵吞枣看十篇教程都有用。推箱子这个题目刚好把所有基础点串了起来——数组、循环、条件判断、面向对象、事件处理、资源加载，而且做出来的成品还能拿去当课程设计、简历项目，甚至给家里人展示，成就感和知识获得感都很足。

如果你照着这份代码敲了一遍，中途卡住了，不妨先自己动手打日志看状态，把地图当前的二维数组打印出来，逐步定位问题。调试排查的功夫，其实是做各种Java项目最有价值的收获之一。

最后分享一个小技巧：不想每次手动去IDE里点运行，可以把代码打包成jar丢在桌面，双击就能玩。打包时记得把bgm.wav也带进jar，用我前面说的getResourceAsStream方式读取音频，这样发给同学，对方不用配置环境也能直接双击跑起来。