简介：这份资源是面向高校计算机相关专业学生与Java初学者的推箱子游戏完整项目，基于Java Swing与Eclipse开发，可作为课程设计、毕业设计选题或Swing图形界面练手案例。压缩包约54.04MB，内含项目全套源码、配套文档与辅导视频，源码均经测试校正，可百分百成功运行，方便读者直接导入Eclipse调试与二次开发。项目围绕推箱子核心玩法展开，涵盖地图关卡设计、角色与箱子移动逻辑、碰撞与胜利判定、界面绘制及事件监听等模块，文档部分则对设计思路与关键代码进行说明，配合辅导视频可帮助读者理解Swing组件布局、图形绘制与游戏循环的实现方式。目前已有939人学习下载，适合需要完整赛题方案、可运行代码与讲解材料的学习者参考借鉴。
1. 从一份课程设计说起：Java Swing 推箱子到底能跑出什么水平
很多人第一次接触 Java 图形界面，都是从推箱子这类小游戏开始的。它不像电商后台那样需要一堆框架，也不像算法题那样只跑黑框，而是把面向对象、事件驱动、二维数组、图形绘制这几件事揉在一个能看见、能点、能玩的项目里。标题里的 Java、Swing、Eclipse 三个词，其实对应了三个很实在的问题：用什么语言写、用什么画界面、在什么工具里调试。推箱子游戏本身规则简单，但真动手做，地图怎么存、人物怎么动、箱子怎么推、关卡怎么切换、撤销怎么做，每一步都能卡住人。这篇文章面向的是正在做课程设计、想拿一份能跑起来的 Swing 项目练手，或者准备把推箱子当成 Java 入门实战的开发者。我会按实际做项目的顺序，把地图数据结构、Swing 绘制、键盘事件、碰撞判定、撤销栈和 Eclipse 调试这几块讲透，代码能直接抄，参数能直接改，坑也提前标出来。
2. 先把地图和角色定下来：二维数组怎么设计才不返工
2.1 推箱子地图的本质是一个带状态标记的二维数组
推箱子看起来是图形，底层其实是一张网格。每个格子有固定属性，比如墙、地板、目标点，还有可移动对象，比如玩家和箱子。最省事的做法是用一个二维整型数组存静态地形，再用单独变量或对象存玩家和箱子的位置。常见做法是定义一套编码：0 表示空地，1 表示墙，2 表示目标点，3 表示箱子，4 表示玩家，5 表示箱子已经在目标点上，6 表示玩家站在目标点上。这样一张地图就是一个 int[][]，加载关卡时直接读数组，绘制时按数字选图片或画颜色。
为什么不用对象数组？因为推箱子关卡通常不大，用 int 编码读写快，调试时打印出来一眼就能看懂。对象数组虽然灵活，但序列化和撤销时会多写不少代码。我一般会先把地图写成文本文件，每行一个字符串，用字符代替数字，加载时再转成 int。这样关卡编辑和修改都方便，不用在代码里手写一堆数字。
// 地图编码：0空地 1墙 2目标点 3箱子 4玩家 5箱子在目标点 6玩家在目标点 public class MapData { // 用字符表示关卡，方便在文本里编辑 public static final char WALL = '#'; public static final char FLOOR = ' '; public static final char TARGET = '.'; public static final char BOX = '$'; public static final char PLAYER = '@'; public static final char BOX_ON_TARGET = '*'; public static final char PLAYER_ON_TARGET = '+'; private int[][] grid; private int playerRow; private int playerCol; private int rows; private int cols; public void loadFromLines(String[] lines) { rows = lines.length; cols = lines[0].length(); grid = new int[rows][cols]; for (int r = 0; r < rows; r++) { for (int c = 0; c < cols; c++) { char ch = lines[r].charAt(c); switch (ch) { case WALL: grid[r][c] = 1; break; case TARGET: grid[r][c] = 2; break; case BOX: grid[r][c] = 3; break; case PLAYER: grid[r][c] = 4; playerRow = r; playerCol = c; break; case BOX_ON_TARGET: grid[r][c] = 5; break; case PLAYER_ON_TARGET: grid[r][c] = 6; playerRow = r; playerCol = c; break; default: grid[r][c] = 0; } } } } }这段代码的关键在 loadFromLines 方法。它把字符逐行转成数字，同时记录玩家初始位置。注意玩家站在目标点上时，格子编码是 6，但玩家位置仍然要单独存，因为绘制时先画地形再画玩家。参数方面，rows 和 cols 由文本行数和每行长度决定，要求每行长度一致，否则会数组越界。实际做的时候，我建议在加载前先检查所有行长度是否相同，不一致直接抛异常，别等到运行时才报错。
2.2 用 Eclipse 建项目时先把包结构分清楚
Eclipse 里新建 Java 项目，名字随便取，比如 SokobanGame。建好之后不要把所有类都塞在默认包，按职责分：model 包放地图和游戏状态，view 包放窗口和绘制面板，controller 包放键盘监听和移动逻辑，util 包放关卡加载和资源读取。这样后面改代码时不会翻半天。Eclipse 的 Package Explorer 里右键 src 新建包，再新建类，比在默认包里堆一堆文件强得多。
资源文件比如关卡文本、图片，放在项目根目录下的 resources 文件夹，不要放在 src 里面。Eclipse 默认会把 src 里的非 Java 文件复制到 bin 目录，但有时候清理项目会丢，放外面更稳。读取时用相对路径，比如 "resources/level1.txt"，在 Eclipse 里运行工作目录是项目根目录，所以能直接找到。如果打包成 jar，就要用 getResourceAsStream，这个后面讲。
提示：Eclipse 新建项目时如果提示模块化，选不创建 module-info.java，Swing 项目用不上，加了反而多一层麻烦。
3. 用 Swing 把地图画出来：JPanel 重绘和图片加载的实操细节
3.1 继承 JPanel 并重写 paintComponent 是唯一正确的绘制入口
Swing 里画自定义图形，标准做法是继承 JPanel，重写 paintComponent(Graphics g)，在方法里根据地图数组画每个格子。不要重写 paint，也不要直接在 JFrame 上画。paintComponent 里第一行通常要调用 super.paintComponent(g)，否则背景可能残留上一帧的内容。绘制顺序是先画地形，再画目标点，再画箱子，最后画玩家，这样玩家永远在最上层。
每个格子的像素大小用一个常量 CELL_SIZE 控制，比如 40。窗口大小就是 cols * CELL_SIZE 和 rows * CELL_SIZE，再加上菜单栏或状态栏的高度。如果地图比窗口大，可以把 JPanel 放进 JScrollPane，但推箱子一般关卡不大，直接固定窗口大小就行。绘制时用 g.drawImage 画图片，或者用 g.fillRect 画色块。用色块调试更快，图片可以后面再换。
public class GamePanel extends JPanel { private MapData mapData; private static final int CELL_SIZE = 40; private Image wallImg; private Image floorImg; private Image boxImg; private Image playerImg; private Image targetImg; public GamePanel(MapData mapData) { this.mapData = mapData; setPreferredSize(new Dimension( mapData.getCols() * CELL_SIZE, mapData.getRows() * CELL_SIZE)); loadImages(); } private void loadImages() { // 图片放在 resources/images 下，用 ImageIO 读取 try { wallImg = ImageIO.read(new File("resources/images/wall.png")); floorImg = ImageIO.read(new File("resources/images/floor.png")); boxImg = ImageIO.read(new File("resources/images/box.png")); playerImg = ImageIO.read(new File("resources/images/player.png")); targetImg = ImageIO.read(new File("resources/images/target.png")); } catch (IOException e) { // 图片缺失时退化为色块，保证程序还能跑 System.out.println("图片加载失败，使用色块绘制"); } } @Override protected void paintComponent(Graphics g) { super.paintComponent(g); for (int r = 0; r < mapData.getRows(); r++) { for (int c = 0; c < mapData.getCols(); c++) { int x = c * CELL_SIZE; int y = r * CELL_SIZE; int cell = mapData.getCell(r, c); // 先画地板 if (floorImg != null) { g.drawImage(floorImg, x, y, CELL_SIZE, CELL_SIZE, null); } else { g.setColor(Color.LIGHT_GRAY); g.fillRect(x, y, CELL_SIZE, CELL_SIZE); } // 再画墙和目标点 if (cell == 1) { if (wallImg != null) g.drawImage(wallImg, x, y, CELL_SIZE, CELL_SIZE, null); else { g.setColor(Color.DARK_GRAY); g.fillRect(x, y, CELL_SIZE, CELL_SIZE); } } else if (cell == 2 || cell == 5 || cell == 6) { if (targetImg != null) g.drawImage(targetImg, x, y, CELL_SIZE, CELL_SIZE, null); else { g.setColor(Color.YELLOW); g.fillOval(x + 10, y + 10, 20, 20); } } // 画箱子 if (cell == 3 || cell == 5) { if (boxImg != null) g.drawImage(boxImg, x, y, CELL_SIZE, CELL_SIZE, null); else { g.setColor(Color.ORANGE); g.fillRect(x + 5, y + 5, 30, 30); } } } } // 最后画玩家 int px = mapData.getPlayerCol() * CELL_SIZE; int py = mapData.getPlayerRow() * CELL_SIZE; if (playerImg != null) g.drawImage(playerImg, px, py, CELL_SIZE, CELL_SIZE, null); else { g.setColor(Color.BLUE); g.fillOval(px + 5, py + 5, 30, 30); } } }这段代码里 CELL_SIZE 是核心参数，改大改小直接影响窗口尺寸和图片缩放。图片加载失败时用色块兜底，这是血泪经验：课程设计答辩时如果图片路径不对，程序直接白屏，老师一问就尴尬。用 ImageIO.read 读文件，路径是相对项目根目录的，Eclipse 运行没问题，但导出 jar 后会找不到，后面会讲怎么改。paintComponent 里不要做耗时操作，比如读文件、网络请求，否则界面会卡。所有图片应该在构造方法里加载好，绘制时只做 drawImage。
3.2 键盘事件绑定用 KeyListener 还是 Key Bindings
Swing 里监听键盘有两种方式：给组件加 KeyListener，或者用 InputMap 和 ActionMap 做 Key Bindings。KeyListener 写起来简单，但要求组件获得焦点，而且焦点丢失后按键就没反应。推箱子这种全程用键盘的游戏，我建议用 Key Bindings，把上下左右绑定到面板的输入映射上，不管焦点在哪都能触发。Eclipse 里写匿名内部类或者 lambda 都行，但 Action 是抽象类，不能直接用 lambda，要写 new AbstractAction()。
// 在 GamePanel 构造方法里绑定方向键 InputMap inputMap = getInputMap(JComponent.WHEN_IN_FOCUSED_WINDOW); ActionMap actionMap = getActionMap(); inputMap.put(KeyStroke.getKeyStroke("UP"), "moveUp"); actionMap.put("moveUp", new AbstractAction() { @Override public void actionPerformed(ActionEvent e) { controller.movePlayer(-1, 0); } }); // 同理绑定 DOWN、LEFT、RIGHT，以及 U 键做撤销WHEN_IN_FOCUSED_WINDOW 表示只要窗口在前台就响应，不用管哪个组件有焦点。参数里 KeyStroke.getKeyStroke("UP") 也可以用 KeyEvent.VK_UP，但字符串写法更直观。绑定之后，移动逻辑交给 controller，面板只负责重绘。每次移动后调用 repaint()，Swing 会自动触发 paintComponent。注意不要在 actionPerformed 里直接改地图数组又同时重绘，逻辑要放在 controller 里统一处理，否则撤销和胜利判定会乱。
4. 移动、推箱子和胜利判定：碰撞逻辑写不对，后面全白费
4.1 一次移动要检查三个格子，不是两个
推箱子的移动规则看起来简单：玩家往一个方向走，如果前面是空地就过去，如果是箱子就检查箱子后面是不是空地或目标点，是就推，不是就不动。但实际写的时候，很多人只检查玩家前面一格，忘了箱子后面那格，结果箱子被推进墙里。正确的做法是：先算玩家目标位置 (nr, nc)，如果越界或者是墙，直接返回。如果是箱子或箱子在目标点上，再算箱子目标位置 (nr + dr, nc + dc)，如果越界、是墙、或者是另一个箱子，返回。只有箱子后面是空地或目标点，才同时移动玩家和箱子。
public boolean movePlayer(int dr, int dc) { int nr = playerRow + dr; int nc = playerCol + dc; if (!isInBounds(nr, nc) || isWall(nr, nc)) return false; int cell = grid[nr][nc]; if (cell == 3 || cell == 5) { // 前面是箱子 int boxNr = nr + dr; int boxNc = nc + dc; if (!isInBounds(boxNr, boxNc) || isWall(boxNr, boxNc)) return false; int boxCell = grid[boxNr][boxNc]; if (boxCell == 3 || boxCell == 5) return false; // 箱子后面还是箱子 // 移动箱子 grid[boxNr][boxNc] = (boxCell == 2 || boxCell == 6) ? 5 : 3; // 原箱子位置变成玩家或目标点 grid[nr][nc] = (cell == 5) ? 2 : 0; } // 移动玩家 int oldCell = grid[playerRow][playerCol]; grid[playerRow][playerCol] = (oldCell == 6) ? 2 : 0; playerRow = nr; playerCol = nc; grid[playerRow][playerCol] = (grid[playerRow][playerCol] == 2) ? 6 : 4; return true; }这段代码里 isInBounds 和 isWall 是辅助方法，判断行列是否在数组范围内、格子是不是 1。注意箱子推到目标点上时编码变成 5，玩家站在目标点上编码变成 6。移动玩家之前，先把玩家原来站的位置恢复成空地或目标点，再更新玩家坐标，最后把新位置设成 4 或 6。顺序不能反，否则会把玩家自己覆盖掉。参数 dr 和 dc 分别是行增量和列增量，上是 -1,0，下是 1,0，左是 0,-1，右是 0,1。
4.2 胜利判定就是检查还有没有箱子不在目标点上
推箱子胜利条件很简单：所有箱子都在目标点上。用编码表示就是数组里不存在 3，只存在 5。每次移动后遍历一遍二维数组，如果找不到 3，就说明赢了。遍历成本很低，关卡最大也就几十乘几十，不用担心性能。胜利后可以弹 JOptionPane 提示，或者切换到下一关。注意不要用箱子数量和目标点数量比较，因为箱子可能在目标点上但玩家还没站上去，编码已经变了，直接查 3 最准。
public boolean isWin() { for (int r = 0; r < rows; r++) { for (int c = 0; c < cols; c++) { if (grid[r][c] == 3) return false; } } return true; }这个方法放在 MapData 里，controller 每次移动成功后调用。如果返回 true，就禁用键盘输入或者弹出对话框。Eclipse 调试时可以在 isWin 里打个断点，看每次移动后数组状态，确认箱子编码有没有正确变成 5。常见错误是箱子推到目标点后编码没改，还是 3，导致永远赢不了。检查 movePlayer 里 grid[boxNr][boxNc] 的赋值逻辑，目标点编码是 2 或 6，推上去要变成 5。
5. 撤销、关卡切换和打包：这些坑我替你踩过了
5.1 撤销用栈存状态，不要存操作
撤销功能是推箱子课程设计的加分项，但实现不好容易出 bug。常见做法是用一个 Stack 存每次移动前的完整地图快照，包括玩家位置和二维数组。移动前把当前状态压栈，撤销时弹出并恢复。不要只存移动方向，因为推箱子可能推箱子，反向操作不一定能还原，比如箱子被推到目标点上，反向拉回来编码会变。存快照最稳，内存占用也不大，一关最多几百步，每步一个二维数组，几十乘几十的 int 数组也就几 KB。
public class GameState { int[][] grid; int playerRow; int playerCol; // 构造方法深拷贝数组 public GameState(int[][] grid, int playerRow, int playerCol) { this.grid = new int[grid.length][]; for (int i = 0; i < grid.length; i++) { this.grid[i] = grid[i].clone(); } this.playerRow = playerRow; this.playerCol = playerCol; } }压栈时 new GameState(grid, playerRow, playerCol)，撤销时 pop 出来恢复。注意深拷贝，否则存的是引用，后面地图一改，栈里的历史也变了。撤销后调用 repaint() 刷新界面。栈用 ArrayDeque 比 Stack 好，Stack 是同步的，没必要。撤销键绑定 U 或者 Ctrl+Z，看习惯。
5.2 关卡切换和资源路径在 Eclipse 内外不一样
关卡切换就是加载下一个关卡的文本，重置地图和撤销栈。关卡文件按 level1.txt、level2.txt 命名，放在 resources/levels 下。加载时用 Files.readAllLines 读所有行，传给 MapData.loadFromLines。切换后重新设置面板的首选大小，调用 revalidate 和 repaint。如果窗口大小固定，直接 repaint 就行。
资源路径在 Eclipse 里用相对路径没问题，但导出成可运行 jar 后，jar 里的文件不能用 File 读，要用 getClass().getResourceAsStream("/resources/levels/level1.txt")。所以读关卡和读图片最好统一用 getResourceAsStream，这样在 Eclipse 和 jar 里都能跑。图片用 ImageIO.read(getClass().getResourceAsStream("/resources/images/wall.png"))，注意路径前面加斜杠表示从 classpath 根开始。Eclipse 里 resources 文件夹要标记为 source folder 或者手动复制到 bin，否则 getResourceAsStream 找不到。我一般把 resources 放在 src 同级，然后在 Eclipse 项目属性里把 resources 加到 Java Build Path 的 Source 选项卡，这样编译时自动复制。
注意：Eclipse 导出 jar 时，如果 resources 没被包含进去，运行 jar 会报 NullPointerException。导出时选 Runnable JAR file，把 resources 一起打包，或者用 Fat Jar 插件。
6. 进阶技巧：用 Eclipse 调试推箱子逻辑和性能优化
6.1 在 Eclipse 里用条件断点抓推箱子越界
推箱子最容易出的 bug 是数组越界，尤其是箱子推到边界时。Eclipse 调试器支持条件断点，可以在 movePlayer 方法里打断点，条件写 nr < 0 || nr >= rows || nc < 0 || nc >= cols，这样只有越界时才停下来。停下来后看 Variables 视图里的 playerRow、playerCol、dr、dc，马上就能定位是哪一步算错了。另一个常用断点是 isWin 返回 true 时，看数组里还有没有 3，确认胜利判定有没有误判。
Eclipse 的 Display 视图可以在调试时执行代码，比如手动调用 mapData.getCell(r, c) 看某个格子的值，不用改代码重新运行。对于推箱子这种状态多的程序，调试器比 System.out.println 高效得多。如果 Eclipse 启动慢，检查 workspace 是不是放在机械硬盘，换到 SSD 会快很多。Eclipse 的自动构建有时候会卡，项目大了可以关掉 Project 菜单里的 Build Automatically，手动 Ctrl+B 编译。
6.2 双缓冲和图片预缩放让界面不闪
Swing 默认是双缓冲的，但如果你在 paintComponent 里频繁缩放图片，还是会卡。优化方法是在加载图片时就缩放到 CELL_SIZE 大小，绘制时直接 drawImage 不缩放。用 Image.getScaledInstance(CELL_SIZE, CELL_SIZE, Image.SCALE_SMOOTH) 或者 BufferedImage 的 getSubimage 加 Graphics2D 绘制。预缩放后每帧绘制就是纯拷贝，速度很快。如果关卡特别大，可以只重绘发生变化的区域，调用 repaint(x, y, w, h)，但推箱子一般不需要。
另一个技巧是把地图绘制结果缓存成 BufferedImage，只有地图变化时才重绘缓存，paintComponent 里直接画缓存图。这样移动玩家时不用重画所有格子，性能提升明显。实现方式是维护一个 BufferedImage cache，在 movePlayer 成功后调用 updateCache()，paintComponent 里 g.drawImage(cache, 0, 0, null)。注意缓存要在窗口大小变化时重建，否则会拉伸变形。
private BufferedImage cache; private void updateCache() { cache = new BufferedImage( mapData.getCols() * CELL_SIZE, mapData.getRows() * CELL_SIZE, BufferedImage.TYPE_INT_ARGB); Graphics2D g2 = cache.createGraphics(); // 这里调用和 paintComponent 一样的绘制逻辑，但画到 cache 上 drawMap(g2); g2.dispose(); } @Override protected void paintComponent(Graphics g) { super.paintComponent(g); if (cache == null) updateCache(); g.drawImage(cache, 0, 0, null); }把绘制逻辑抽成 drawMap(Graphics2D g) 方法，paintComponent 和 updateCache 都调用它，避免代码重复。cache 用 TYPE_INT_ARGB 支持透明图片。每次移动、撤销、切换关卡后调用 updateCache() 再 repaint()。这个优化在关卡多、格子多的时候效果明显，普通课程设计可能感觉不到，但养成习惯没坏处。
我做了几个 Swing 项目之后最大的教训是：界面卡顿和图片丢失，九成是资源加载和重绘逻辑没写好，跟 Java 性能没关系。把图片预缩放、路径统一用 getResourceAsStream、绘制逻辑抽干净，推箱子这种小游戏在十年前的笔记本上都能跑得很顺。希望帮到你。
本文还有配套的精品资源，点击获取
