简介纯 JavaScript 编写的 3D 魔方模拟程序适合前端初学者、算法爱好者以及想了解魔方还原逻辑的开发者只需浏览器即可交互体验魔方旋转并观察每一步状态变化。压缩包共 21 个文件含 15 个 js、4 个 css、1 个 html 和 1 张 png大小仅 255KBjs 中既有魔方状态管理和旋转算法也有基于 Three.js 的 3D 渲染与动画处理css 负责页面外观与响应式布局。已有 779 人浏览学习作者精简了从 Google 收集的原始代码去除了冗余部分可读性和运行效率都更高。借助这个项目能深入理解 DOM 事件、对象建模、动画循环及递归回溯在魔方求解中的应用也可直接将核心模块改造为自己项目的交互组件是一份轻量又完整的前端实战参考。 手写一个“魔方代码 纯JS版”这事我琢磨了很久。不是因为魔方本身有多难而是市面上现成的方案要么绑死Three.js要么把渲染和还原算法焊死在一起想改点交互逻辑都无从下手。最后我干脆关了文档用原生JavaScript从零写了一个可交互、可打乱、可判断复原的3D魔方没引任何框架纯JS加CSS 3D搞定。这篇文章就把整个实现过程、核心数据结构和一些调试时踩过的坑都记录下来给想自己动手做一遍的人当参考。如果你是刚接触前端不久想找一个小而完整的项目练手或者你已经写过一些页面但没碰过三维变换、旋转矩阵这类东西那这个项目都很适合。它难的地方不在写代码而在理解状态和渲染的关系这部分想通了剩下的就是体力活。1. 认知先行纯JS实现魔方难点不在“3D渲染”1.1 这个项目到底要做什么先把需求拆清楚。我目标中的“魔方代码”不是写一个静态展示模型而是一个能玩的3D魔方呈现一个完整的3×3魔方能自由旋转视角点击或拖拽能转动某一层符合真实魔方的操作直觉支持随机打乱并判断魔方是否已经复原全流程只使用原生JavaScript不依赖Three.js、不依赖后端。那时候我查了一圈资料发现大部分开源项目都把“魔方还原算法”和“魔方渲染”混在一起代码动辄上千行找不到切入点。还原算法是搜索问题渲染和交互是三维图形问题两者根本是两条独立的技术线。所以我就决定这个版本先不做智能还原只做“可玩的魔方”把状态管理和3D交互的基础打好后面想加还原算法直接在状态层上扩展就行。1.2 三条渲染路线为什么我选了CSS 3D浏览器里做3D渲染大的路线就三条。我做了个对比方案实现方式优点缺点CSS 3D Transform每个小面是一个div用transform定位代码简单、动画省心、不依赖GPU编程DOM节点较多复杂场景吃力Canvas 2D手动把三维坐标投影到二维平面自由度最高、代码量最少遮挡关系、光照、深度判断全要自己写WebGL底层GPU渲染性能强、效果上限高学习成本大为了一个3×3魔方杀鸡用牛刀我实测下来54个小面片6面 × 9格对CSS 3D完全没压力transform-style: preserve-3d一开立体感直接就出来了。动画交给transition浏览器自动算插值人畜无害。Canvas 2D其实也写过一版核心思路是把每个顶点做透视投影然后按深度排序绘制多边形但透明度、光照、边缘抗锯齿都要自己处理工作量翻倍。所以最终选了CSS 3D路线。2. 数据结构与旋转算法别用“贴纸”用“块”2.1 为什么不用54张贴纸我第一次写的时候踩进过“贴纸方案”的坑。什么叫贴纸方案就是把魔方想象成6个二维平面每面9格共54格旋转面的时候直接把格子里的颜色数组做交换。听起来很直接写起来也确实快但后面会暴露三个硬伤数据与渲染割裂你维护的是“哪个位置是什么颜色”这层抽象但3D渲染时每张贴纸在空间里是有实际坐标的。颜色交换和坐标变换是两套逻辑同步起来非常痛苦。做不了旋转动画贴纸交换是瞬间的如果你想看“一面90度转过去”的过渡效果需要额外的动画状态机相当于从零再搭一遍。扩展性差想高亮某个块、想跟踪某一块的位置、想判断复原状态靠颜色数组都很难搞。所以我推翻重来改用“块模型”。一个3×3×3的魔方中心块不动、中心轴上的块只有两个面可见、普通块三个面可见去重后一共26个小方块。每个块有自己固定的颜色组合和三维坐标旋转时改变的是块的坐标与朝面而不是把颜色数据复制来复制去。这才符合现实中魔方的物理规律。2.2 旋转的核心其实就是坐标变换公式魔方任意一层旋转90度本质上是对这一层所有小方块的坐标做一个三维旋转变换。这里需要一点线性代数基础但别怕用数学公式太抽象我用最直白的方式说。把旋转拆开来看绕某个轴旋转时这个轴上的坐标分量不变另外两个分量按照二维平面旋转公式变化。比如绕Y轴顺时针旋转90度站在Y轴正方向往原点看xoz平面的旋转公式是x z z -x绕X轴和绕Z轴同理只是参与变换的坐标分量不同。我把三种轴的旋转逻辑直接写成一个纯函数function rotatePos(pos, axis, dir) { let { x, y, z } pos; // dir: 1 顺时针从轴正方向看-1 逆时针 switch (axis) { case x: return dir 0 ? { x, y: -z, z: y } : { x, y: z, z: -y }; case y: return dir 0 ? { x: z, y, z: -x } : { x: -z, y, z: x }; case z: return dir 0 ? { x: -y, y: x, z } : { x: y, y: -x, z }; } }这个函数不带任何DOM操作入参出参都是纯数据所以特别好测试。我当时把26个块的坐标全部打出来手动用一个真实魔方对照验证了几组旋转确认无误后才继续往下写。2.3 状态层和渲染层必须分开这是整个项目里我觉得最值得分享的设计思路。魔方旋转的流程看起来是“转一面”但仔细想它包含了两类信息一是块的位置和朝向变了逻辑状态二是视觉上这面转过去了视觉表现。我让立方块对象Cubelet只保存逻辑坐标和六个面的颜色不直接操作DOM。真正的DOM渲染由一个渲染器Renderer负责它会读取每个Cubelet的逻辑坐标换算成对应的CSS transform。旋转动作触发时逻辑坐标立刻更新为新位置渲染层用一个过渡动画展示旋转过程动画结束后渲染层把子块的最终位置落到新坐标上并清理临时动画状态。这样做最大的好处是后添加的交互、检测、还原逻辑只需要跟纯数据打交道完全不需要关心CSS有多复杂。这个思路其实和后端常用的状态机设计如出一辙状态定死再谈表现。3. 实操过程从零搭一个可复现的纯JS魔方3.1 初始化场景与小方块的颜色推导先准备一个3D场景容器设置好perspective和transform-style然后生成26个小方块。每个方块展开成6个面片通过rotateX、rotateY、translateZ组合成一个空心立方体。这里有个关键点面片颜色不要硬编码而是根据块的坐标实时推导。function getFaceColor(x, y, z, face) { // face: front | back | left | right | up | down // 坐标取值范围-1、0、1 if (face right x 1) return R; if (face left x -1) return L; if (face up y 1) return U; if (face down y -1) return D; if (face front z 1) return F; if (face back z -1) return B; return #111; // 内部面涂深色 }这样做的好处是即使某个块经过几十次旋转颜色依然由坐标唯一决定不会出现颜色错位。实际开发中硬编码颜色在初始状态看起来没问题但多做几次旋转后错误很难定位而推导式写法的检错成本低很多。3.2 交互设计用拖拽方向识别要转的层交互我尝试过两个方案。第一版是做“点击高亮面片再选择旋转方向”逻辑清晰但手机上体验很差两次点击太繁琐。最终改成了拖拽识别记录鼠标/手指按下时的坐标和松开时的坐标计算位移向量。位移向量的处理有几个细节只保留横纵方向中位移绝对值更大的那个作为主方向防止斜向拖动造成歧义屏幕坐标的“上下左右”不能直接映射到三维旋转轴需要结合当前视角的旋转角度做一层换算位移阈值控制在10像素左右太短视为误触不触发操作。function handleSwipe(dx, dy, view) { const isHorizontal Math.abs(dx) Math.abs(dy); const direction (isHorizontal ? dx : -dy) 0 ? 1 : -1; // 根据视角得到当前对应的旋转轴 const axis getActiveAxis(isHorizontal ? h : v, view); rotateLayer(axis, direction); }换算轴的时候我当时打印了不少日志。经验是先用正视角固定测试确认横纵映射正确后再引入视角旋转分步骤调试比一次性写完省时间。3.3 旋转动画transition是所有方案里最省心的CSS 3D旋转动画的实现思路是把参与旋转的9个小方块放到一个临时容器里然后让这个容器整体做一次transform过渡取得旋转轴对应的立方体中心作为transform-origin给容器设置transition: transform 0.3s ease将容器的transform设置为对应轴的90度旋转监听transitionend事件在回调里更新所有小方块的逻辑坐标再将容器transform清零。用transition做动画的好处是浏览器负责所有中间帧的计算代码量极少。动态插值过程不需要逐帧更新CPU占用很小在移动端上也流畅。我试过用requestAnimationFrame写跟手拖拽那是另一套复杂玩法如果不是做“手指捏着魔方块拖动”的物理交互用transition就足够了。提示CSS 3D的transform顺序千万别乱写。rotateX(90deg) rotateY(45deg)和rotateY(45deg) rotateX(90deg)的结果完全不同初始化所有块的时候就约定统一顺序后面才不会乱。3.4 打乱和复原判断比想象中简单打乱算法本来我准备写一个随机转动的序列但实际只需要注意两点。一是连续转动同一层没有意义随机序列里要过滤掉二是打乱动画和用户手动操作要互斥否则动画还没结束用户又拖了一下状态直接乱套。我用一个简单的Promise队列串行执行所有旋转动作每步动画结束后才执行下一步。复原判断这个需求我一开始想复杂了试图通过“每个块的位置和朝向是否等于初始状态”来判断。后来发现完全不用管块的朝向只需要检查6个大面的颜色分布是否还原function isSolved(cube) { for (const face of faces) { const standard face.standardColor; const stickers face.getAllStickerColors(); if (!stickers.every(c c standard)) return false; } return true; }因为魔方的物理特性决定了只要六大面颜色正确每个块的朝向一定也正确。所以判断逻辑不用搞什么深度遍历逐个面比对颜色就行。4. 常见问题与排查技巧实录4.1 旋转后小方块“飞掉”或者变形这是我遇到的第一个大bug第一次旋转完几个小方块直接跑到了场景外。排查后发现问题出在“逻辑坐标已更新但渲染层没有同步新坐标”或者反过来渲染层改了transform但父容器的临时旋转没重置导致坐标叠加两遍。排查思路是先把每个Cubelet的逻辑坐标打印出来与视觉位置比对。如果坐标对而画面错问题在渲染层如果坐标本身就不对回去检查旋转映射函数。4.2 拖拽方向老是反的方向反了说白了是旋转正方向的定义不统一。屏幕坐标的y轴向下而三维坐标的y轴通常向上直接套用会差一个负号。解决办法是建立一套统一约定以“从轴向正方向看向原点逆时针为正”为唯一标准所有旋转映射函数都遵守这个定义。交互层换算时再做一层符号修正这样即使出错也能顺着映射表快速定位。4.3 页面卡顿和内存持续上涨54个DOM节点本身不卡但如果每次旋转后销毁重建DOM就会又卡又吃内存。优化方案是初始化时一次创建全部节点之后只修改transform和类名绝不重建。如果还卡则优先检查CSS里有没有多重阴影、模糊滤镜等GPU高消耗效果那些视觉效果对性能的拖累远超DOM节点数量。4.4 CSS 3D的背面可见性魔方的小方块如果设置为双面可见旋转到背面时会透出另一面的颜色看起来乱成一团。解决办法是给每个面片添加backface-visibility: hidden这样视觉上只显示朝外的面。这个属性对不透明面片效果稳定但如果你用了半透明材质就需要额外处理否则会看到透明底下的内部结构。4.5 移动端滑动冲突在手机上页面滚动和魔方旋转都依赖手势容易误触。我的处理方式是给魔方容器设置touch-action: none阻止浏览器手势默认行为然后在拖拽逻辑里加入位移阈值判断。只有手指真实移动超过阈值才触发转动否则视为点击或取消操作。现象核心原因解决方向方块飞掉逻辑坐标与渲染坐标不同步打印坐标定位是状态还是渲染问题方向反向正方向约定不统一统一旋转方向标准交互层做符号修正卡顿、内存涨频繁重建DOM初始化建好全部节点只改transform显示乱色双面渲染加backface-visibility: hidden手势误触页面滚动与拖拽冲突设置touch-action增加位移阈值判断整个项目做下来我最深的体会是纯JS写3D魔方真正的坑不在算法也不在CSS而在【数据结构】。一开始我用贴纸方案写了两天越写越卡换成块模型之后状态更新、动画驱赶、交互映射全都顺了。建议想动手实践的朋友开局花心思把CubeState和Renderer两个模块拆干净后面做高亮、做还原算法、做多阶魔方都不用改底层代码。另外一个小技巧调试旋转逻辑时可以在场景里放一个只涂三种颜色的测试块旋转几轮后通过颜色判断块有没有跑偏比盯着坐标数组直观得多。本文还有配套的精品资源点击获取