事情是这样的，有天我看到别人的网页魔方演示，直接在浏览器里就能拖拽旋转、打乱还原，当时我就想，这玩意儿到底怎么实现的？后来查了一下，发现核心其实就是 HTML 加 Three.js，用不到多少行代码就能拼出一个能交互的 3D 魔方。这个项目很适合想入门 Three.js 的前端同学来做练手，既能吃到 WebGL 的基础概念，又能把几何体、射线检测、动画控制这些知识点串起来。今天我就把这个网页魔方的完整实现思路、踩过的坑和可复现的代码一次性讲清楚。
1. 动手前先想明白：网页魔方到底该怎么做
1.1 为什么是 Three.js，而不是其他方案
做 3D 网页，可选的路其实不少。国内搜“threejs和unity哪个好”的人很多，但我觉得这个问题得分场景：Unity WebGL 适合完整游戏，导出体积动不动几十兆，加载速度和浏览器兼容性都要操不少心；CSS3D 适合做简单卡片翻转，但真要做 27 个小块自由旋转的魔方，它的变换矩阵推导会让人怀疑人生；原生 WebGL 更不用说了，几百行代码只够画个三角形，做一个完整的魔方交互起码要一两千行。
Three.js 正好卡在中间：它把 WebGL 的复杂 API 封装到了“场景、相机、渲染器”这套直觉化的模型里，同时保留了矩阵变换、射线检测这些底层能力，非常适合做这种中轻量级的 3D 交互应用。网页魔方这个项目，本质上是“一堆小方块 + 分轴旋转 + 点击拾取”的组合，Three.js 每个点都有现成方案，不需要走弯路，所以我最后选它。
1.2 技术方案选型对比
我做之前先拉了一张对比表，把主流路线都过了一遍：
| 方案 | 上手难度 | 旋转层动画 | 浏览器兼容 | 体积 | 适合情况 |
|---|---|---|---|---|---|
| CSS3D | 低 | 但需要手动处理矩阵，层级嵌套复杂 | 较好 | 小 | 简单卡片、弱 3D 效果 |
| Three.js | 中 | 有现成 Group / Matrix 方案 | 较好 | 约 600KB，可压缩 | 中型 3D 交互，推荐 |
| 原生 WebGL | 极高 | 全部自己写数学 | 完全可控 | 无依赖 | 学习/底层定制 |
| Unity WebGL | 较高 | 成熟但重 | 一般 | 巨大 | 完整游戏项目 |
结论很明显：像网页魔方这种需要快速迭代、又要保证交互流畅感的项目，Three.js 是最优解。它的数学库自带旋转矩阵和向量运算，能省下大量调试时间。
1.3 核心实现思路拆解
一个标准三阶魔方是 3×3×3 的格子，也就是 27 个小块（角块 8 个、棱块 12 个、中心块 6 个，外加最中心那个看不见的核心块）。网页魔方的实现思路可以拆成四层：
- 基础场景层：创建 Three.js 场景、透视相机、WebGL 渲染器，再补环境光和方向光，让方块有立体感。
- 物体构造层：创建一个小方块，六个面涂上不同颜色；通过坐标规律摆出 27 个方块，组成一个完整魔方。
- 交互控制层：用鼠标点击/拖拽，识别用户要旋转哪一层、朝哪个方向转，通过射线检测和矩阵变换实现。
- 动画反馈层：把一次 90 度旋转拆成多帧动画，让旋转过程平滑，避免瞬间跳变。
这四层是非常经典的前端 3D 项目分层方式，理解之后不光是魔方，类似的 3D 交互小项目（拼图、骰子、积木）都能按这个套路来做。
2. 从零搭建基础场景
2.1 页面骨架与引入 Three.js 的方式
先写一个最标准的 HTML 文件。这里建议不要用file://协议直接双击打开，尤其当你用的是 ES Module 方式引入时，浏览器会因跨域限制拦下脚本。后面问题排查部分我会细说，这里先把骨架摆出来：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>网页魔方 - Three.js 实现</title> <style> html, body { margin: 0; height: 100%; overflow: hidden; background: #1a1a2e; } canvas { display: block; } #info { position: absolute; bottom: 20px; left: 50%; transform: translateX(-50%); color: #fff; font-family: sans-serif; font-size: 14px; background: rgba(0,0,0,0.5); padding: 8px 16px; border-radius: 8px; pointer-events: none; } </style> </head> <body> <div id="info">拖动旋转视角 · 点击并拖拽可以转动魔方层 · 双击归位</div> <script type="importmap"> { "imports": { "three": "https://unpkg.com/three@0.160.0/build/three.module.js", "three/addons/": "https://unpkg.com/three@0.160.0/examples/jsm/" } } </script> <script type="module"> import * as THREE from 'three'; import { OrbitControls } from 'three/addons/controls/OrbitControls.js'; // 后面的代码都在这个模块里写 </script> </body> </html>这里用到了 importmap，它能让我们在浏览器里直接用import语法引入 Three.js 和官方扩展包，不需要 npm 和打包工具，对纯静态页面来说非常方便。如果你用 Vite 等工程化环境，那更简单，直接 npm install three 即可。注意 importmap 里指向的 CDN 版本，不同版本的 API 有细微差异，建议锁死版本号。
2.2 场景、相机、渲染器、灯光四件套
Three.js 的固定套路是：创建一个场景（Scene），创建相机（Camera），创建渲染器（Renderer），最后在动画循环里不断渲染。我把这段封装成一个initBase()函数，逻辑直观一点：
const scene = new THREE.Scene(); const camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 100); camera.position.set(6, 6, 10); camera.lookAt(0, 0, 0); const renderer = new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(window.innerWidth, window.innerHeight); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); document.body.appendChild(renderer.domElement); // 灯光：环境光保证暗面不至于全黑，平行光承担主要立体感 const ambientLight = new THREE.AmbientLight(0xffffff, 0.6); scene.add(ambientLight); const dirLight = new THREE.DirectionalLight(0xffffff, 0.8); dirLight.position.set(5, 10, 7); scene.add(dirLight); // 轨道控制器：允许整体旋转观察，后续和魔方层旋转做区分 const controls = new OrbitControls(camera, renderer.domElement); controls.enableDamping = true; controls.enablePan = false; controls.minDistance = 5; controls.maxDistance = 30;这段代码里有几个细节值得说一下。antialias: true能明显减少模型边缘的锯齿，代价是性能略微下降，魔方这种直线边缘多的模型，不开抗锯齿会非常难看。devicePixelRatio控制在 2，是因为高 DPI 屏上如果无限拉高像素比，性能和显存都会受不了，画面还没明显提升。
灯光数量不用多，一环境光加一方向光足够。很多新手一上来加五个灯光，结果画面要么过曝要么阴影混乱。WebGL 场景里灯光数量直接影响着色器复杂度，能用两盏解决就别用五盏。
2.3 做出第一个好看的小方块
一个标准魔方小方块，单纯用THREE.BoxGeometry加上六面不同颜色材质就能做成。但这样看起来棱角太锐利，缺少真实魔方的“圆角贴纸”质感。我做了个折中方案：外层用稍大的圆角立方体，六个面贴上带圆角的彩色贴纸。
圆角立方体可以用 Three.js 官方仓库里的RoundedBoxGeometry，它位于three/addons/geometries/RoundedBoxGeometry.js。引入方式：
import { RoundedBoxGeometry } from 'three/addons/geometries/RoundedBoxGeometry.js';然后创建一个带有六种面颜色的小块：
const size = 0.95; // RoundedBoxGeometry 没有现成 face 材质数组，这里先用方盒子做主体结构 const geometry = new THREE.BoxGeometry(size, size, size); const materials = [ new THREE.MeshStandardMaterial({ color: 0xC41E3A }), // 右 +X 红 new THREE.MeshStandardMaterial({ color: 0xFF5800 }), // 左 -X 橙 new THREE.MeshStandardMaterial({ color: 0xFFFFFF }), // 上 +Y 白 new THREE.MeshStandardMaterial({ color: 0xFFD500 }), // 下 -Y 黄 new THREE.MeshStandardMaterial({ color: 0x0051BA }), // 前 +Z 蓝 new THREE.MeshStandardMaterial({ color: 0x009E60 }), // 后 -Z 绿 ]; const cube = new THREE.Mesh(geometry, materials);这里有个容易搞混的点：BoxGeometry的材质数组顺序是固定的，依次对应右、左、上、下、前、后六个面，不是随便排的。我第一次做的时候把顺序写反，结果按红色面转了一圈，背后露出白色，排查了半天才发现是材质列表顺序的问题。
如果你想更真实一点，可以给六个面做“黑底圆角贴纸”效果。方法是用 Canvas 画一个黑色方块，中间留白色圆角区域，再作为贴图贴到每个面上。这样渲染出来每个小块的黑色边框就会形成类似魔方缝隙的视觉效果，整体观感会提升一大截。这个属于锦上添花，基础功能的实现不受影响。
2.4 动画循环与窗口缩放处理
场景搭完，必须有一个持续渲染的循环：
function animate() { requestAnimationFrame(animate); controls.update(); // 更新轨道控制器阻尼 renderer.render(scene, camera); } animate(); window.addEventListener('resize', () => { camera.aspect = window.innerWidth / window.innerHeight; camera.updateProjectionMatrix(); renderer.setSize(window.innerWidth, window.innerHeight); });requestAnimationFrame会跟随屏幕刷新率执行，通常 60 次每秒，是浏览器推荐的动画循环方式。如果你在这里用的是setInterval，有可能掉帧，而且后台标签页也不会自动暂停，浪费资源。resize 监听是为了拖动浏览器窗口后，画面不至于变形，这是一个固定操作，每次做 Three.js 项目都建议顺手加上。
到这里，我们已经能在浏览器里看到一个小块和可转动的视角了。接下来才是真正的重头戏：怎么把它拼成一个能转的魔方。
3. 组装完整魔方与层级结构
3.1 27 个小块的坐标规律
标准三阶魔方以中心为原点，每个小方块边长 1，那么所有块的坐标就是x, y, z ∈ {-1, 0, 1}的三个正交组合，总共 27 个。用两层循环生成即可：
const cubes = []; for (let x = -1; x <= 1; x++) { for (let y = -1; y <= 1; y++) { for (let z = -1; z <= 1; z++) { const cube = createCube(x, y, z); cube.position.set(x, y, z); scene.add(cube); cubes.push(cube); } } }为了让每个小方块之间留出恰到好处的缝隙，我把方块边长设成了 0.93 而不是 1。这样视觉上能分清个体，旋转时又不会因为间隙太大看起来松散。不同魔方模型对缝隙处理不同，有人喜欢用 0.9，有人用 0.98，这个参数可以放到文件顶部统一配置，方便后面调。
3.2 颜色分布方案
真实魔方六面颜色是固定的相对关系：白对黄、红对橙、蓝对绿。为了让用户看到的是“正经”魔方，我按如下规则给每个方块上色：
| 坐标方向 | 朝向 | 颜色 |
|---|---|---|
| x = 1 的面 | 右 | 红 |
| x = -1 的面 | 左 | 橙 |
| y = 1 的面 | 上 | 白 |
| y = -1 的面 | 下 | 黄 |
| z = 1 的面 | 前 | 蓝 |
| z = -1 的面 | 后 | 绿 |
实现时，最直观的做法是：每个方块都创建六个标准材质，然后根据方块所在坐标隐藏那些在内部的面上对应的颜色（把内部材质改成深灰/黑色）。这样每个方块渲染出来只在朝外的面上显示彩色，内部面呈现“黑色边框”的观感，非常贴近真实魔方。
function buildMaterials(x, y, z) { const faceColors = [ x === 1 ? 0xC41E3A : 0x111111, // 右 x === -1 ? 0xFF5800 : 0x111111, // 左 y === 1 ? 0xFFFFFF : 0x111111, // 上 y === -1 ? 0xFFD500 : 0x111111, // 下 z === 1 ? 0x0051BA : 0x111111, // 前 z === -1 ? 0x009E60 : 0x111111, // 后 ]; return faceColors.map(color => new THREE.MeshStandardMaterial({ color })); }如果懒省事，也可以所有小块六个面都上色，这样魔方内部也会花花绿绿，旋转时露出内部会显得不够真实。用黑色处理内部，是花同样运行成本就能提高观感的小技巧。
3.3 为什么这里不推荐“几何体合并”
热词里有“threejs合并几何体”，我猜不少人会把魔方理解为 27 个 BoxGeometry 合并成一个几何体，听起来能减少 draw call，很合理对吧？实际这是个坑。
BufferGeometryUtils.mergeGeometries能把多个几何体一次性合并成一个，合并后总共只有一个 Mesh，确实性能极好。但问题是：合并之后，几何体的每个顶点虽然保留了位置，却丢失了一个东西——它原本属于哪个独立方块。一旦你想让某一层的 9 个方块整体旋转 90 度，你会发现自己没法单独操作这 9 个方块，因为它们已经焊在同一个几何体里分不开了。
有人会说，可以记录顶点在哪些索引范围内，按范围拆分更新矩阵。理论上行得通，但实现复杂度比直接保留 27 个独立 Mesh 高一个量级，完全没必要。魔方动画的本质是“9 个对象组成一组，绕着轴转过 90 度”，天然适合用THREE.Group配合独立 Mesh 来做。合并几何体更适合那些静态、不用拆分的模型，比如场景里的桌面、地板、背景墙。
所以我最后的方案是：27 个独立 Mesh 共存于场景中，每次旋转只处理其中一层的 9 个。Three.js 默认的渲染优化可以让同材质物体自动批处理，27 个小方块的 draw call 根本构不成性能压力。
3.4 层级设计与层数据管理
为了支持“整层旋转”，需要动态地把同一层的 9 个方块放进同一个临时组（Group）里，旋转后再拆出来放回场景。具体流程是：
- 点击/拖拽事件计算出要旋转哪一层、绕哪个轴。
- 遍历
cubes数组，找到符合条件（比如 y = 0）的 9 个方块。 - 把这 9 个方块从场景中
remove出来，添加到一个新建的 Group 中。 - Group 绕对应轴旋转目标角度。
- 动画结束后，把方块从 Group 中拆出，重新
add回场景，并同步世界变换。
这里的核心是“临时分组、转完归位”的思想。用代码表达大致如下：
function rotateLayer(axis, layerIndex, targetAngle, done) { if (rotating) return; rotating = true; const group = new THREE.Group(); cubes.forEach(cube => { const pos = cube.position.clone(); if (axis === 'y' && Math.round(pos.y) === layerIndex) { cube.position.set(0, 0, 0); group.add(cube); } }); scene.add(group); // 动画旋转 targetAngle 度数 const startAngle = 0; const duration = 300; const startTime = performance.now(); function step(now) { const t = Math.min(1, (now - startTime) / duration); const eased = t; // 可替换为缓动函数 if (axis === 'y') group.rotation.y = THREE.MathUtils.degToRad(targetAngle * eased); else if (axis === 'x') group.rotation.x = THREE.MathUtils.degToRad(targetAngle * eased); else if (axis === 'z') group.rotation.z = THREE.MathUtils.degToRad(targetAngle * eased); if (t < 1) { requestAnimationFrame(step); } else { // 动画结束，把方块拆回场景 scene.remove(group); group.children.forEach(cube => { cube.updateWorldMatrix(true, false); cube.getWorldPosition(cube.position); cube.getWorldQuaternion(cube.quaternion); scene.add(cube); }); rotating = false; if (done) done(); } } requestAnimationFrame(step); }动画结束的拆分组动作很关键。不懂的人会直接在 Group 里留着方块继续旋转，第二次再点击时，那块的位置已经跟着 Group 走偏了。正确做法是每次转完都把方块的位姿“烘焙”回自己的 transform 属性里。
这里有个小坑：cube.position在 Group 里是相对 Coord，拆出来时要调用getWorldPosition和getWorldQuaternion同步到绝对坐标，否则位置会全乱。
3.5 坐标归整与浮点误差
连续旋转几次之后，方块的世界坐标可能会出现1.0000000000000002这种浮点结果。如果下一轮直接用这个数判断是否属于某一层，会遇到“找不到层”的尴尬。所以每次旋转完，做一个坐标四舍五入：
cube.position.x = Math.round(cube.position.x); cube.position.y = Math.round(cube.position.y); cube.position.z = Math.round(cube.position.z);同时把旋转四元数也尽量整化到 90 度的倍数，或者允许一个极小误差。这一步不做，魔方玩十几次后大概率卡死或者层乱掉。浮点误差在 3D 应用里是经典敌人，任何涉及网格对齐的应用都要记得做量化处理。
4. 交互操作实现与动画细节
4.1 明确交互方式：整体视角旋转 vs 魔方层旋转
这里有个交互设计的取舍。如果直接用 OrbitControls，鼠标拖动会旋转整个世界视角，那我们就没有手势去拧魔方了。我的方案是：
- 鼠标在魔方上按下并拖拽：优先判定为“拧层”，通过射线检测选中的方块和拖拽方向决定旋转。
- 鼠标点击到空白区域：切换为 OrbitControls 整体旋转视角。
- 双击魔方任意块：恢复初始视角/姿态。
这个划分不是唯一的，也有人用快捷键切换“观察模式”和“拧动模式”，但对网页展示来说，最直觉的就是直接按物理直觉旋拧。用户看到魔方，第一反应就是去拨动感兴趣的那一层。
4.2 Raycaster 点击识别与选层逻辑
Three.js 内置了Raycaster，可以发射一条射线，检测哪些 Mesh 被击中。这个功能是实现点击选层的基石。代码如下：
const raycaster = new THREE.Raycaster(); const pointer = new THREE.Vector2(); function onPointerDown(event) { pointer.x = (event.clientX / window.innerWidth) * 2 - 1; pointer.y = -(event.clientY / window.innerHeight) * 2 + 1; raycaster.setFromCamera(pointer, camera); const intersects = raycaster.intersectObjects(cubes); if (intersects.length > 0) { // 拿到了击中的小方块 const hitCube = intersects[0].object; const face = intersects[0].face; // face.normal 决定了点击的是哪个面，从而决定拧层轴和方向 } }这里需要稍微解释一下face和normal。射线撞到 BoxGeometry 的某个面，face.normal就是该面的单位法向量，比如撞到上表面，法向量就是(0, 1, 0)。通过法向量就能知道这次点击应该旋转哪个轴：
- 法向量 y 分量绝对值最大 → 点击到上下表面 → 绕 y 轴旋转这一层。
- 法向量 x 分量绝对值最大 → 点击到左右表面 → 绕 x 轴旋转。
- 法向量 z 分量绝对值最大 → 点击到前后表面 → 绕 z 轴旋转。
但这里还有一个关键问题：点击一个面，只能确定轴，不能确定是哪一层。比如点中了上表面一个方块，这层是 y=1 还是 y=0？答案是看击中时射线命中的是哪个方块，然后用该块的坐标来算层号。因为点击的是表面，命中的方块必然位于该方向的最外层，所以层号就是那个方向坐标值。
const normal = face.normal.clone(); // 因为是网格几何体且有变换，normal 可能是局部坐标，需要经过物体矩阵转换 const worldNormal = normal.transformDirection(hitCube.matrixWorld); let axis, layerIndex; if (Math.abs(worldNormal.x) > 0.9) { axis = 'x'; layerIndex = Math.round(hitCube.position.x); } else if (Math.abs(worldNormal.y) > 0.9) { axis = 'y'; layerIndex = Math.round(hitCube.position.y); } else { axis = 'z'; layerIndex = Math.round(hitCube.position.z); }这个逻辑做完，点击选层的第一步就通了。难点在于法向量从局部坐标转换到世界坐标，如果你忽略了transformDirection，旋转后的魔方会出现“点上面却提示转左右”的错乱现象。我之前在这里卡了半个多小时，所以写出来提醒大家。
4.3 拖拽方向判定与旋转目标角度
点击选层解决的是“旋转哪个轴、哪一层”，接下来需要根据拖拽方向决定“转 90 度还是 -90 度”。我是这样写的：记录手指/鼠标落点，在鼠标移动过程中不断计算横向和纵向位移，运动累计到阈值（比如 20 像素）时触发一次旋转。
判定逻辑：
- 如果是绕 y 轴旋转：鼠标横向拖动方向 右 → 转 +90°，左 → 转 -90°。
- 如果是绕 x 轴：鼠标纵向拖动方向 上 → 转 +90°，下 → 转 -90°。
- 绕 z 轴同理，看顺/逆时针。
结合刚才选出的面，其实还有更精细的判定方式：用鼠标移动方向向量与法向量做叉积，得出绕轴方向和角度符号。这种方法更通用，单手操作也更自然，但代码会稍微长一点。我想给读者的建议是：先取简化方案，能用就行，等玩熟了再改精细判定。
另外加一个状态锁rotating，保证动画过程中不允许再叠加一次旋转。原因很简单：旋转过程是渐变的，如果中途再次修改 Group 的 rotation，新旧角度会叠加，动画趋势不可控。锁住之后用户的体验是“转完这一下才能继续拨”，像真实魔方一次只能拨一层，反而更符合直觉。
let dragging = false; let pressPos = { x: 0, y: 0 }; let pendingAxis = null; let pendingLayer = null; renderer.domElement.addEventListener('pointerdown', (e) => { dragging = true; pressPos = { x: e.clientX, y: e.clientY }; // 这里完成选层，结果存进 pendingAxis / pendingLayer }); renderer.domElement.addEventListener('pointermove', (e) => { if (!dragging || rotating) return; const dx = e.clientX - pressPos.x; const dy = e.clientY - pressPos.y; if (Math.hypot(dx, dy) < 20) return; let targetAngle = 0; if (pendingAxis === 'y') targetAngle = dx > 0 ? 90 : -90; else if (pendingAxis === 'x') targetAngle = dy > 0 ? -90 : 90; else if (pendingAxis === 'z') targetAngle = ...; // 按视觉方向判定 rotateLayer(pendingAxis, pendingLayer, targetAngle); dragging = false; }); renderer.domElement.addEventListener('pointerup', () => { dragging = false; });用pointer事件而不是兼容性较差的mouse/touch分开写，可以省很多代码量，移动端也能直接响应触摸，对网页演示来说非常实用。
4.4 旋转动画的缓动与手感优化
基础旋转动画只要按时间插值即可，但直接线性插值会有突兀的启停感，给用户的感觉是“僵的”。我建议加缓动函数：
function easeInOutCubic(t) { return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2; }在step里把线性t换成缓动后的eased，旋转就会有一个自然的加速减速过程。实际体验下来，这个小小的改动让整个魔方的手感从“玩具塑料滑块”变成“机械顺畅机构”，像素级的细节往往决定了 Demo 的高级感。
动画时长我也建议控制在 200ms 到 400ms 之间。太短显得暴躁，太长拖沓，300ms 是我试过最舒服的。”可以自己调一调感受下。
4.5 打乱与还原的思路
要让用户玩得起来，打乱是必要的。最简单的打乱策略：从还原状态执行随机旋转 30 次，每次不展示动画，直接把层层旋转到目标角度并烘焙。核心代码如下：
function scramble() { const axes = ['x', 'y', 'z']; const layers = [-1, 0, 1]; for (let i = 0; i < 30; i++) { const axis = axes[Math.floor(Math.random() * 3)]; const layer = layers[Math.floor(Math.random() * 3)]; const angle = Math.random() > 0.5 ? 90 : -90; doInstantRotate(axis, layer, angle); } }doInstantRotate就是rotateLayer去掉动画、直接设置最终角度的版本。注意打乱时最好连续旋转不同层，避免两条连续命令互相抵消，视觉上打乱效果不好。可以用一个简单约束：下一次选的轴和上次不相同。
还原方式我更推荐“魔方状态记录 + 逆序还原”，而不是一帧一帧回放之前操作。前者逻辑简单：每次旋转时把旋转记录 push 到一个数组里，点击还原按钮时，从数组尾到头，逐条反向执行，并且这次带动画，能看到魔方一步步拧回去。这条逻辑适合对状态管理还不熟的人入手。
5. 常见问题与排查技巧实录
5.1 双击 HTML 文件打开只有黑屏
这是 Three.js 新手最常见的问题。原因大概率是 ES Module 加载跨域被拦。浏览器对file://协议的模块加载有安全限制，不会像 http 那样宽松。解决办法一般是开一个本地静态服务器：
python -m http.server 8080然后浏览器访问http://localhost:8080即可。如果不想装 Python，用 VS Code 的 Live Server 插件也行，或者 Node.js 生态里的npx serve。总之，不要直接双击 HTML 文件，这是模块化开发的基本常识。
检查顺序：先打开开发者工具看 Console 有没有红色报错，如果是 CORS 或者Failed to fetch，十有八九是静态服务器的问题。
5.2 画面是黑漆漆的一片，方块看不见
有几种可能：相机朝向不对；方块不在场景中心；灯光没加导致 MeshStandardMaterial 显示出纯黑；或者材质用了 MeshBasicMaterial 但颜色全是 0。查这个问题最有效的办法是：
- 把相机位置打印出来，
camera.position，确认它在方块附近。 - 临时把材质换成
MeshBasicMaterial，如果此时能看到形状，说明是灯光问题。 - 确认方块位置在可见范围内，必要时设置
camera.lookAt(0, 0, 0)。
5.3 点击选中层的方向与预期相反
这种问题一般出在法向量世界坐标转换上。很多老教程只针对未旋转模型做射线检测，拿到的face.normal直接使用。但魔方旋转后，Mesh 自身有复杂变换，局部法向量和世界法向量方向完全不同。务必调transformDirection(hitCube.matrixWorld)做转换。
如果还是反向，那就手动把旋转目标角度加个负号。反正交互手感这个东西两极分化，有人习惯顺时针拖，有人习惯逆时针拖，按照自己的习惯定就好。
5.4 旋转几次后魔方散架或层判断错乱
这就是浮点误差累积问题。每次旋转结束后一定要做坐标归一化，把position四舍五入到最近的整数，把quaternion也尽量量化。我遇到的最极端例子，是旋转 50 次后某个块坐标变成(0.99999994, 1.0000001, 0)，用Math.round处理后就恢复正常了。
另外要注意，临时分组再拆回场景时，cube.position会被修改为世界坐标。如果之前这个块在另一个 Group 里，它的matrixWorld是复合变换，拆组后必须在updateWorldMatrix之后再取坐标和旋转。顺序反了，取到的是旧值。
5.5 移动端手势和 PC 端混乱
如果项目只做桌面展示，可以只监听pointer事件。但如果兼容移动端，最好统一用pointerdown/move/up，不要混着用mouse和touch，否则会出现一次点击同时触发两个事件、拖拽时动画卡顿的问题。pointer事件天然统一了鼠标、触屏和笔，是比较省心的方案。
真机上测试时记得设置touch-action: none，否则浏览器会把横向滑动解析成页面滚动，导致魔方划不动。
5.6 常见问题速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 黑屏，Console 报 CORS | file 协议打开页面 | 起本地静态服务 |
| 黑屏，Console 无报错 | 相机朝向/距离不对 | 调整相机或 lookAt |
| 方块没有立体感 | 缺灯光 | 添加环境光+方向光 |
| 点击选不中物体 | 射线检测对象不对 | intersectObjects(cubes)传入子 Mesh |
| 旋转方向反了 | 法向量未转换 | 用transformDirection |
| 多次旋转后魔方乱掉 | 浮点误差累积 | 四舍五入坐标和四元数 |
| 移动端拖拽没反应 | touch-action 未设置 | CSS 添加touch-action: none |
6. 结尾：一点个人体会
我第一次做完这个网页魔方的时候，最大的感受是：原来 3D 交互没那么玄。Three.js 把 WebGL 的底层复杂度藏得很深，让你可以把精力集中在场景结构、交互逻辑和动画设计上。但你也不要因为它看上去简单就跳过数学基础，旋转矩阵、四元数、零向量转换这些概念在后面迟早会用上。所有跳过的数学都会在调试散架魔方时加倍还回来。
如果你想在现有项目上继续扩展，我建议可以从这几个方向入手：给魔方加计时器和打乱序列统计，做成一个完整的在线魔方计时器；也可以用键盘快捷键控制层旋转，做出一套“教学模式”，引导用户按步骤还原。无论选哪个方向，你都绕不开这个项目里练到的同一套能力：场景管理、射线拾取、动画控制和状态同步。把它完整做一遍，前端 3D 的门就算正式迈进去了。
