推箱子小游戏实战1.0：地图碰撞与状态管理的完整复盘

推箱子这种老掉牙的玩法，为什么我还会专门写一篇实战复盘？因为越简单的项目，越能看清一个开发者的基本功。地图数据怎么组织、移动碰撞怎么判定、撤销功能怎么设计、关卡死局怎么避免——这些不只是推箱子的问题，而是几乎所有2D网格类游戏都会碰到的核心问题。这个推箱子小游戏实战1.0是我近期带一个新人练手时搭的项目，前后折腾了两个周末，不算大，但足够把“从零到一个能玩的产品”这条路完整走一遍。如果你也是刚接触游戏开发，或者想用一个小项目把数据结构和逻辑设计串起来，这篇复盘应该能给你不少参考。

1. 推箱子项目的目标设定与整体方案

动手写代码之前，先想明白一件事：这个1.0版本到底要做到什么程度。很多人一开始就想着加动画、加音效、加关卡编辑器，结果核心玩法还没跑通，代码已经乱成一团。我给自己定的目标是先把闭环打通——地图能加载、人物能移动、箱子能推动、推到目标点能判定胜利、卡死能重置。这五件事做完，推箱子就算“能玩”了，后续再谈优化和扩展。

1.1 项目目标与边界

我一直在跟别人强调一个观点：做小游戏，第一版一定要克制。推箱子小游戏实战1.0这个版本，我明确划出的边界是——不做连续动画过渡，不做步数统计和计时器，不做多关卡选择界面，甚至不做撤销功能（后面会在常见问题里专门讨论为什么撤销值得做但也很容易翻车）。这些不是不重要，而是不能在第一版混淆主次。

这个版本的核心目标是让玩家“能玩完一关”，而且玩的过程中不能出现明显反直觉的情况。什么叫反直觉？比如箱子推过去了，人物站在箱子原来的位置，但看起来像穿模了；或者目标点上已经放了箱子，渲染时却被其他格子盖住；再或者连续按方向键时人物滑得停不下来。这些都是第一版就要避开的硬伤。

适合来看这篇内容的人，我觉得有三类。第一类是完全没写过小游戏、想找第一个练手项目的初学者；第二类是写过一些页面但没处理过“地图+碰撞+状态管理”这类逻辑的开发者；第三类是正在带新人做实战项目的导师或组长，可以参考我这里的模块划分和踩坑记录。如果你已经做过这类项目，可以直接跳到第4节看问题排查部分，那部分是我觉得最值得存档的经验。

1.2 技术选型：为什么用Canvas加JavaScript

市面上做小游戏的方案很多，光前端就有纯DOM、Canvas、WebGL，再加上各种游戏引擎。为什么第一版选了Canvas加原生JavaScript？说穿了就是三个词：依赖少、好调试、够用。

纯DOM方案其实也能做推箱子，用绝对定位的div块模拟地图格子，写起来甚至更简单，但一旦涉及到“箱子被推动时格子的状态刷新”，DOM方式要频繁操作节点属性，逻辑分散而且性能上限低，做1.0可以，往后想加动画就会很痛苦。游戏引擎方案则反过来，能力很强但学习曲线陡，为了一个推箱子引入引擎，相当于用卡车搬一箱牛奶，配置成本超过了收益。

Canvas在这个项目里的定位是“一块画板加一个重绘机制”。每按一次方向键，我就把整张地图按当前状态重绘一遍。推箱子这个游戏的画面复杂度有限，一个关卡几十个格子，重绘一次连一毫秒都用不到，根本不需要做局部刷新的优化。选Canvas最大的好处是状态和画面分离得很干净：逻辑层只管地图数组和角色坐标，渲染层只负责把数组画出来，两者之间靠一个简单的渲染函数对接。这个模式后面想加动画、加特效都方便，因为底层渲染接口没变，变的只是画法。

还有一点，用原生JavaScript写，对新人来说每一步都是透明的。用引擎的话，很多功能是被封装好的，出了Bug你只能猜；原生环境下所有代码都在你手里，出问题可以一步步跟，这对学习阶段来说太重要了。

1.3 模块划分与数据流

这个小项目虽然小，我仍然按模块拆了代码，而不是把所有逻辑塞进一个文件里。大概分成五个部分：

• 地图数据模块：负责关卡地图的存储和解析
• 游戏状态模块：维护玩家坐标、箱子坐标、当前步数、当前关卡
• 输入处理模块：监听键盘事件，转换成游戏指令
• 逻辑判定模块：执行移动、推箱、胜利判定
• 渲染模块：把状态画到Canvas上

这五个模块之间的调用关系是一条直线：“输入 -> 修改状态 -> 触发重绘”。没有双向依赖，没有事件总线，就是最朴素的单向数据流。新手容易犯的一个错误是让渲染模块直接去修改游戏状态，比如“画箱子的时候发现箱子在目标点上，就把某个变量改了”，这样看着省事，但会让状态变得不可预测。我这里的做法是渲染之前先把所有状态计算好，渲染模块只读状态，不改状态。

数据流设计好之后，后续加功能就变成了“在输入处理里加一种指令”或者“在渲染模块里多画一种元素”，不会牵一发动全身。这个模块划分的经验，我觉得比具体代码更值得你抄走。

2. 核心玩法背后的关键设计

推箱子的核心玩法看起来就那几个操作，但背后涉及的数据结构设计、碰撞检测、状态同步，都是值得掰开揉碎讲的东西。这一节我不会贴全部代码，而是把几个最关键的设计决策拆开分析，尤其要讲清楚“为什么这样设计”。

2.1 地图如何用数据表达

地图是整个游戏的基石。我用的方案是二维数组加三层数据分离：静态层存墙和空地，目标层存目标点，动态层存箱子和玩家。为什么这么分？因为它们的生命周奇完全不一样。墙和空地从头到尾不变，目标点也基本不变（玩家站在目标点上也不影响目标点本身），但箱子和玩家的坐标每走一步都在变。如果把所有信息混在一个二维数组里，移动逻辑里就要反复处理“格子原来是什么、现在变成什么”，很容易出错。

用一个简化地图举例，地图数据长这样：

##### # # # $ # # . # # @ # #####

其中#是墙，$是箱子，.是目标点，@是玩家。我实际代码里并没有直接用字符，而是把它们解析成数字。静态层中0表示空地、1表示墙；目标层中0表示不是目标、1表示是目标；动态层中0表示空、1表示箱子、2表示玩家。这样每次移动只需要管动态层，静态层和目标层只用来做碰撞判定和胜利判定。

解析字符地图的好处是直观，我需要改关卡时不用去数数组里哪个数字对应哪个格子，直接看字符就能理解布局。这个设计在1.0版本里省了很多调试时间，后面如果你要做关卡编辑器，同样能复用这套字符格式。

2.2 移动与推动的碰撞判定

这一步是整个游戏的心脏。玩家按一下方向键，程序要做的事情是：先算出玩家下一步要去的格子坐标，然后看这个格子里有什么，如果是墙就不动；如果是空地或目标点，直接走；如果是一个箱子，就继续看箱子的下一个格子，如果下一个格子是墙或另一个箱子就推不动，否则就推。这个逻辑用伪代码写出来很清晰：

next = 玩家坐标 + 方向向量 如果 next 是墙: 不移动 如果 next 是空地或目标点: 玩家移动到 next 如果 next 是箱子: next2 = 箱子坐标 + 方向向量 如果 next2 是墙或箱子: 不移动 否则: 箱子移动到 next2 玩家移动到 next

代码实现的时候有几个细节要注意。第一，方向向量的定义直接对应键盘事件，上就是(-1,0)，下是(1,0)，左是(0,-1)，右是(0,1)，让坐标和画面方向保持一致，减少心智负担。第二，边界检查必须做，不要以为地图四周都是墙就不会越界，设计关卡时可能手滑留了缺口，运行时越界访问数组会直接报错。第三，更新顺序很重要，先确认整个移动合法，再同时更新玩家和箱子坐标，不要走一步更新一步，否则推到一半发现推不动，状态就乱了。

这一块是新手最容易写飘的地方。我见过很多人把移动逻辑拆成“玩家先走、再检查碰撞、不行就退回”，这样当然也能跑，但边界情况会特别多。最稳妥的方案就是上面这种“先判断后执行”，一次键盘事件只产生一次确定的状态变更。

2.3 胜利判定与通关条件

胜利判定看起来简单，但有一个很容易忽略的点：什么时候判定。如果只在玩家按完方向键之后判定一次，那么箱子被推上目标点的瞬间就要立刻检查，否则玩家会在“箱子已经到位但游戏没反应”的状态下多操作一步，体验很怪。

我的做法是在每次移动成功、状态更新完之后立即调用一个检查函数。检查逻辑也很直接：遍历所有箱子的坐标，看它们每一个是否都落在目标点上。这里顺便说一个优化思路，如果你在后面做步数统计或者音效反馈，可以用一个计数器，每次箱子从非目标点移到目标点就加一，从目标点移到非目标点就减一，判断计数是否等于箱子总数，这样比每次遍历所有格子要快一些，而且能区分“这次的移动导致了目标达成”。

通关之后做什么？1.0版本里我做了三件事：显示一个通关文案、播放一个简单的界面闪烁效果、自动跳到下一关。如果当前已经是最后一关，就显示全部通关。这里有一个平衡问题——反馈太少让人觉得没反应，反馈太多又打断节奏。我的经验是，文案和视觉提示够了，第一版不要加弹窗，弹窗会挡住玩家想继续看下一关地图的欲望，直接切换关卡反而更顺。

3. 实操过程：从零搭起可玩版本

这一节我会按实际开发顺序，把从画布初始化到完整跑通整个流程的步骤过一遍。每个步骤我都会交代当时的想法和后面踩到的坑，方便你照着做的时候避开。

3.1 第一步：搭建基本骨架和初始化画布

页面结构不复杂，一个Canvas画布加一个状态栏区域，再加一个重置按钮。我直接创建Canvas，固定尺寸，比如一个关卡有10列6行，每个格子画成64像素，那画布就是640乘384，四周再留一点边距。为了适配不同屏幕，我给画布设置了CSS的max-width，让它按比例缩放，但内部的逻辑坐标始终用格子数量计算，不跟CSS尺寸挂钩。

初始化的时候，要一次性把画布的尺寸、地图数据、玩家出生点、箱子初始位置全部准备好。这里有一个容易忽略的问题：解析地图时，遇到@和$，要记录下它们的坐标，并且把地图中对应位置标记为空地。如果不这样做，绘制的时候会出现一个格子里既画了墙又画了玩家的情况，虽然代码不会报错，但画面会错乱。

这个阶段只做一件事：打开页面能看到一张静态的地图。不要急着写移动逻辑，先确认地图解析和绘制是对的，后面出了问题也容易排查。

3.2 第二步：地图渲染与精灵绘制

渲染部分的核心是一个drawGame函数，它每次从动态层和静态层取数据，逐个格子绘制。基本思路是：先画静态层，把墙和空地铺满整个画布；再画目标点；最后画动态层，也就是箱子和玩家。顺序不能乱，如果先画了箱子和玩家再画目标点，目标点就会盖住箱子，导致“箱子在目标点上”的视觉反馈消失。

画格子我用的方案是Canvas的fillRect铺底色加strokeRect描边。墙用深灰色，空地用浅灰色，目标点用带圆心的圆圈，箱子用棕色的方块，玩家用蓝色圆点。不用图片素材，纯代码绘制，好处是省去加载图片的麻烦，而且换主题色只需要改几个变量。实际上到后面想把箱子画成带木纹的样子，也是在这个基础上加细节，渲染接口不用变。

一个实用的技巧：每一个可绘制元素我都单独拆成一个函数，比如drawBox(context, x, y)、drawPlayer(context, x, y)。这样后续要加选中效果、高亮效果都方便。不要在一个函数里把所有绘制逻辑堆完，那种代码改起来真的很痛苦。

3.3 第三步：接入键盘输入与移动逻辑

键盘监听用keydown事件，监听哪些键呢？我同时支持方向键和WASD，因为有些笔记本用户会觉得方向键离左手太远。处理事件时要注意一件事：按下方向键时，页面会滚动，所以需要调用preventDefault阻止默认行为，不然玩着玩着页面就滚走了。

拿到按键之后，把方向映射成方向向量，然后调movePlayer函数。movePlayer内部按前面讲的“先判断后执行”的流程做碰撞检测和移动。这一步做完，游戏已经有了基本可玩性，可以试着把一个箱子推到目标点上，看判定是否正常。

这个阶段比较容易出现的问题在连续按键上。如果你用的是keydown，按住方向键不放会不断触发事件，玩家会“滑步”。1.0版本我保留了这种连续响应，因为推箱子是个解谜游戏，不是动作游戏，按住连走反而方便。但如果你不想这样，可以加一个简单的锁：在移动执行期间忽略新的键盘事件，或者记录最后一次按键的timestamp，只有间隔大于某个阈值才响应。

3.4 第四步：胜利反馈与关卡循环

胜利判定写完以后，要把它接进游戏主循环。我的实现里，玩家每完成一次成功移动，就调用checkWin，如果有箱子全部到位，就把当前关卡标记为完成，然后展示通关文案，800毫秒后加载下一关。

关卡数据的组织方式我在这一步也一并做好了。用一个数组存所有关卡的地图字符串，加载下一关时把索引加一，如果索引超出数组长度就表示全部通关。通关之后显示的文案别太长，一两句话就行，比如“恭喜通关，你一共推了多少步”，这样既给了成就感，又不至于让玩家等太久。步数统计在1.0里我是做了的，因为它太简单了——每次成功移动加一，重置时清零——成本几乎为零但效果很好。

这里我特别想提醒一点：加载新关卡之前，一定要重置所有状态变量。很多人会漏掉箱子坐标的初始化，导致玩完第一关，第二关的箱子位置还是第一关的。一个统一的重置函数在进入任何关卡时都要调用，它要做的事情包括：重新解析地图、重置玩家坐标、重置箱子坐标、清零步数、清空操作记录（如果你做了撤销）。

3.5 第五步：重置功能与状态隔离

重置按钮看起来简单，实际上是对游戏状态管理的一次考验。正常逻辑是：点击重置，回到这一关的初始状态，步数清零。实现起来就是保存一份关卡初始状态的快照，重置时把当前状态恢复成快照的值。

有一个细节：快照存的是二维数组，不要直接赋值引用，要用深拷贝。JavaScript里数组是引用类型，如果你把初始地图数组直接存下来，后面一动动态层，快照也跟着变了，重置就失效了。我在这上面栽过跟头，后来专门写了个深拷贝函数，每次进入关卡时调用。这个经验同样适用于你后面做撤销功能——撤销要恢复的也是完整的对象快照，不是某个单独的坐标。

4. 常见坑与排查技巧实录

这一节是这篇内容里我最想让你们仔细看的部分。每个坑都是我实际踩过的，有些问题看着很小，排查起来却要花不少时间。我把它们整理成了问题描述、原因分析、解决方案三段式，方便你遇到类似情况时直接对照。

表格是一个很好的速查形式，我把最典型的几个问题先列出来，后面再逐个展开。

4.1 人物穿墙与滑步问题

穿墙这个问题，原因通常是碰撞检测写得不完整。比如只检查了玩家下一步的格子，没检查箱子能不能继续往前；或者把坐标更新放在了碰撞检测之前，导致检测用的是旧数据，更新用的是新数据，两边对不上。我排查这种问题时习惯在移动函数里打断点，观察next坐标和地图里的格子的类型，一眼就能看出来是检测逻辑漏了还是写错位置。

滑步问题前面提过，基本是键盘事件连续触发导致的。如果你不想要连续响应，可以用一个“响应锁”或者记录上次处理时间的方式。不过在我这个1.0版本里，连续滑动反而被当成一个特性保留了下来——推箱子不像动作游戏，快一点慢一点影响不大，至少我测试玩下来没觉得别扭。

4.2 箱子推入死角后无法通关

这是一个关卡设计问题，代码层面其实没有“错”，但玩家体验会很差。比如一个箱子被推到了墙角，没有任何方向能把它推出来，这时候整关就无解了。1.0版本我采取的方案很朴素：提供一个重置按钮，玩家觉得没救了就点一下。后来我还给重置按钮加了一个确认弹窗，防止玩家误触，不过弹窗只在这一关已经推了很多步之后才出现，如果刚开始几步就重置，直接重置就好，不用弹窗。

从关卡设计的角度，我还发现一个规律：好的推箱子关卡，箱子应该尽量在一个开阔的区域里移动，不要让玩家在早期就能把箱子推进死角。设计关卡时我每设计一版都会自己玩几遍，确认箱子在推的过程中都有至少一条“回头路”，也就是任何箱子在任何阶段都不会被推进一个完全封闭的区域。这个检查做多了，关卡质量能明显提升。

4.3 渲染闪烁与性能问题

Canvas重绘本身很快，但如果你在绘制代码里做了多余的事情，比如每次重绘都重新解析一次地图字符串、或者每次都创建一个新的渐变色对象，累计起来就会感觉卡。我遇到过的一个真实场景是：某次我给箱子加阴影效果，用了Canvas的阴影API，结果每画一个箱子都开启阴影，一关有二十来个箱子，每帧都要计算多次阴影，游戏明显变卡。后来我把阴影的偏移和模糊改成预计算的参数，只在绘制时作用，性能就正常了。

另一个经验是不要用setInterval做重绘驱动。推箱子这个游戏的状态只在玩家操作时改变，所以重绘只需要在状态改变之后触发一次。用setInterval每16毫秒画一次，浪费性能不说，还会在不需要刷新的时候产生多余的绘制。我用的方案是“移动完成后调用drawGame”，简单直接。

4.4 撤销功能为什么容易做崩

我在最初规划1.0时没有做撤销，后来测试发现有些关卡玩家推错一步就满盘皆输，重置又太粗暴，于是决定补一个撤销功能。这个功能本身不难，难在如何处理“撤销”和“胜利判定”“步数统计”之间的关系。

我的实现方案是维护一个操作历史栈，每次成功移动之前，把当前状态压入栈；撤销时从栈里弹出上一份状态，恢复所有坐标和步数。这个方案有两个容易出现Bug的点。第一，如果你记录的是“移动之后的快照”而不是“移动之前的快照”，撤销一次就会回到上一步而不是回到更早的状态，逻辑会差一格。第二，步数在撤销后应该回退，很多人在实现时忘了回退步数，结果为了一致性又要额外维护一个步数历史，代码越改越乱。

实际上，如果你刚开始做这类游戏，我建议第一版不做撤销功能。因为它对核心玩法没有影响，却要引入“历史状态”的概念，会显著增加代码量。等核心闭环稳定了，再作为增强功能加上去，会从容很多。我在这个项目里是先加了重置功能，确认重置稳定了，才在分支里做的撤销，这样就算撤销写崩了，主版本也不受影响。

5. 一些收尾的个人体会

这个1.0版本做完，我最大的感受是：推箱子虽然玩法简单，但它把“状态管理”这件事体现得非常完整。你有一个地图，地图上有一些会变化的元素，玩家通过一系列操作改变这些元素的状态，程序需要保证任何一步操作之后，整个画面的状态都是自洽的。这个能力迁移到其他项目里，不管是做表格编辑、拖拽交互，还是做更复杂的游戏，本质上都是一回事。

还有一点体会是关于“边界”的。做这个小项目时我把范围卡得很死，坚决不加动画、不加音效，结果核心功能两天就稳定了。后来把动画和音效补上去，其实也没花多少时间，而且因为核心稳定，加东西的时候心里不慌。很多项目做砸不是因为功能太少，而是因为第一版就想把所有东西都塞进去，结果核心逻辑被各种边缘功能淹没，出了问题都不知道该查哪里。

如果你也在做类似的练手项目，我的建议很简单：先把核心玩法跑通，跑通之后再去想“酷炫”的事。一个能玩的、逻辑严密的推箱子，比一个花里胡哨但卡顿的“增强版”靠谱得多。这版1.0之后我打算加的东西是关卡编辑器和步数排行榜，逻辑已经在脑子里过了一遍，等动手做完，再来分享2.0实战记录。