t3code 是我最近在维护的一个 Three.js 项目代号整个仓库里收集的是各种可复用的 3D 场景示例从最基础的盒子渲染到稍微复杂一点的交互模型加载都有。起这个名字就是因为 Three.js 的 three 读起来像 t3再加上 code方便自己记后来也顺手拿它当项目文件夹名没想到一用就用了大半年。这个项目主要解决一件事 让前端开发者不用被原生 WebGL 劝退而是通过 Three.js 快速做出能看、能点、能玩的 3D 页面。如果你正打算从零接触 3D 开发或者已经在用 Three.js 但总感觉场景一复杂就发蒙那这篇文章里的设计思路、参数计算和调试方法应该对你有帮助。我会把 t3code 里我自己踩过的一些坑和验证过的操作细节都摊开讲尽量让小白也能照着写。1. 整体设计与技术选型1.1 为什么选 Three.js 而不是原生 WebGL我刚开始做 3D 时也纠结过这个问题 到底是直接撸 WebGL API 还是用 Three.js。后来在 t3code 里写了几个对比小例子体验差别非常明显。原生 WebGL 需要考虑缓冲区、着色器编译、矩阵变换一个旋转立方体就得几十行起而 Three.js 帮你把这些底层细节都封装好了Scene、Mesh、Camera、Renderer 几个核心对象一组合三五行代码就能出画面。但这不代表 Three.js 是个黑盒。它只是把 GPU 管线的常规操作模板化比如你依然需要理解顶点、片元、光照这些概念只不过由 Three.js 帮你生成默认着色器。对于产品页面、数据可视化、3D 展厅这类场景Three.js 的性价比是最高的。t3code 的目标不是绕开复杂度而是让你在可控的复杂度内把事做成。1.2 t3code 的功能规划与场景设计在设计 t3code 的时候我先列了几个必须满足的基础能力 场景得能旋转模型得能加载鼠标点一下物体得有反馈。这三个能力几乎覆盖了 80% 的 Web 3D 需求所以我把它拆成了三个独立模块每个模块都能单独复用。第一个模块是基础场景包括渲染器、透视相机、环境灯光和地面网格第二个模块是模型加载支持 glTF 格式的模型和纹理第三个模块是射线拾取通过鼠标点击事件选中场景里的物体并做出反应。这样的结构有点像搭积木每个模块之间通过场景对象衔接后续新增功能时不会互相牵制。你如果自己搭项目也建议先按能看、能动、能交互这个顺序去规划比一上来就堆一堆高级效果要稳得多。2. 核心细节解析与实操要点2.1 三维坐标系与相机参数计算刚接触 Three.js 时最容易懵的就是坐标系。Three.js 默认使用右手坐标系 X 轴向右Y 轴向上Z 轴朝屏幕外。也就是说在场景里放置物体时正 Z 方向是朝自己负 Z 方向是朝向屏幕里面。这是个很基础但很容易搞反的点我在 t3code 里特意在场景中心放了一个轴辅助就为了时刻提醒自己。相机参数方面透视相机是最常用的它模拟人眼的近大远小效果。构造函数是 PerspectiveCamera(fov, aspect, near, far)。fov 是视场角单位是度一般设置在 45 到 75 之间fov 越大看到的范围越广但是物体显得越小aspect 是画布的宽高比通常是 window.innerWidth / window.innerHeightnear 和 far 是近裁剪面和远裁剪面意思是在这个范围内的物体才会被渲染。实际使用时有几个细节需要注意。比如 near 和 far 的差值不要太大否则会出现深度精度问题远处物体闪烁或者看不清。一个常见经验是把 far 设成场景最远物体的 2 到 3 倍就行没必要给个十万八万的。t3code 里的默认参数是 fov 60aspect 根据窗口动态计算near 0.1far 1000。如果场景中需要看到很远的天空盒可以适当把 far 拉大但一定要同时测试地面的遮挡关系防止视觉错误。2.2 场景组织与性能优化要点性能优化往往是新手最容易忽略的。刚开始做 t3code 时我直接把十个模型全丢在场景里动画一跑就掉帧后来才明白每次绘制都是要付出代价的。Three.js 的渲染是按 draw call 来计算的每个 Mesh 单独加入场景时渲染器需要发送多次绘制指令。一个可行的办法是使用 InstancedMesh把大量相同几何体的顶点数据合并到一次绘制里完成。比如场景里有 100 个同样的小方块用普通 Mesh 需要 100 次 draw call用 InstancedMesh 只需要 1 次。对于大量重复物体这个优化效果非常明显。另一个优化点是纹理压缩和加载策略。t3code 里为了避免模型加载时白屏我会用 RGBELoader 加载环境贴图同时把大纹理图拆成 mipmap 级别让 GPU 在更远距离显示低分辨率贴图。这些操作不会让画面变差反而能大幅降低 GPU 压力。记住一个原则 不是所有物体都需要高精度的贴图离得远的、小的物体完全可以用压缩纹理。3. 实操过程与核心环节实现3.1 初始化项目与基础场景搭建我建议你用 Vite 加 npm 来搭项目因为 Vite 的即时冷启动对开发体验提升很大。先初始化一个 vanilla 项目然后安装 three代码里通过 npm 包的方式引入即可。不需要什么复杂的脚手架一个 index.html 加一个 src 目录就够用。下面是最基础的一段初始化代码import * as THREE from three; const scene new THREE.Scene(); const camera new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.1, 1000); camera.position.set(5, 5, 5); 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 geometry new THREE.BoxGeometry(1, 1, 1); const material new THREE.MeshStandardMaterial({ color: 0x4a90d9 }); const cube new THREE.Mesh(geometry, material); scene.add(cube); const light new THREE.DirectionalLight(0xffffff, 1); light.position.set(3, 5, 4); scene.add(light); function animate() { requestAnimationFrame(animate); cube.rotation.x 0.01; cube.rotation.y 0.01; renderer.render(scene, camera); } animate();这段代码跑起来后你会在窗口中间看到一个旋转的立方体光源从右上方向打过来立方体有阴影和立体感。l这里有一个容易踩的坑 如果直接使用 MeshBasicMaterial它不受光照影响画面会显得很平没有立体感。t3code 里我用的都是 MeshStandardMaterial它是基于物理的材质对光照更真实但需要场景里至少有一个光源否则物体会是全黑的。很多新手第一次跑看到黑色物体以为代码错了其实就是因为没加光源。3.2 添加交互控制与动画场景搭好之后最自然的需求就是让用户能自由旋转视角。这一步我推荐使用 three/examples/jsm/controls/OrbitControls 这个控制器它实现了鼠标拖拽旋转、滚轮缩放和右键平移是我在这个项目里最喜欢的自带扩展。接入方式也简单在动画面循环里更新控制器的状态import { OrbitControls } from three/examples/jsm/controls/OrbitControls.js; const controls new OrbitControls(camera, renderer.domElement); controls.enableDamping true; controls.dampingFactor 0.05; controls.minDistance 2; controls.maxDistance 20; function animate() { requestAnimationFrame(animate); controls.update(); renderer.render(scene, camera); }enableDamping 开启后视角移动会带有一点惯性手感更顺滑但别忘了 update() 方法要在渲染循环里调用。还有一个细节是我不建议把阻尼系数调太低0.03 到 0.08 之间比较舒服太大会显得拖泥带水太小又像没有阻尼。动画这一块除了在循环里手动修改 rotation 以外还可以用 Clock 对象来获取时间差这样可以保证动画速度在不同帧率下基本一致。比如让立方体每秒旋转 30 度而不是每帧旋转固定角度。代码大概是这样const clock new THREE.Clock(); function animate() { const delta clock.getDelta(); cube.rotation.y Math.PI / 6 * delta; renderer.render(scene, camera); }这样即使屏幕刷新率从 60Hz 变成 144Hz动画速度也不会变化。性能好的时候更流畅性能差的时候只是掉帧但不会疯转。3.3 加载外部模型与事件拾取t3code 里另一个重量级功能是加载外部模型。目前最通用的格式是 glTF它是三维行业的交换格式体积小、加载快。Three.js 里有现成的 GLTFLoader需要从 examples 里引入。同时要配合加载器设置路径否则模型内部的纹理容易加载失败。代码示例import { GLTFLoader } from three/examples/jsm/loaders/GLTFLoader.js; const loader new GLTFLoader(); loader.load(/models/robot.gltf, (gltf) { scene.add(gltf.scene); });加载器回调里拿到的是 gltf它内部包含 scene、animations 等属性。注意要把 gltf.scene 加到主场景而不是把整个 gltf 对象加进去。这是新手最容易错的一步我一开始写漏了结果页面什么都没显示。事件拾取则要用到 Raycaster 和 Vector2。思路是 把鼠标点击的位置转换成标准化设备坐标NDC然后用射线检测场景里的物体。你可以这样实现const raycaster new THREE.Raycaster(); const pointer new THREE.Vector2(); window.addEventListener(click, (event) { pointer.x (event.clientX / window.innerWidth) * 2 - 1; pointer.y -(event.clientY / window.innerHeight) * 2 1; raycaster.setFromCamera(pointer, camera); const intersects raycaster.intersectObject(cube); if (intersects.length 0) { cube.material.color.set(0xff5533); } });这里把鼠标坐标从像素值转换到 -1 到 1 的区间y 轴要取反因为屏幕坐标和 NDC 坐标的 y 方向是相反的。我经常看到有人掉了这个负号导致点击永远对不上排查半天。还有一点如果场景里物体比较多建议用 intersectObjects(scene.children, true) 并开启递归检测但要注意性能物体太多时可以分组检测或者手动指定被检测的数组。4. 常见问题与排查技巧实录4.1 场景渲染不出来或黑屏这是 t3code 群里被问得最多的问题。遇到黑屏先不要急着改代码从几个固定方向查。第一检查相机位置。如果相机位置是 (0, 0, 0)而且物体也在这个点附近相机可能嵌在物体内部看起来就像画面一片黑或者模糊。把相机往后拉移动到 (5, 5, 5) 再 lookAt 原点就能解决。第二检查是否有光照。之前提到 MeshStandardMaterial 需要光源没有光源就是全黑。第三检查渲染器的 canvas 是否被 CSS 遮住了。最常见的是 html 和 body 默认 margin 为 8px或者画布被某个 div 盖住看着像没渲染出来。我建议在场景里先加一个 AxesHelper能看到坐标轴就说明渲染链路通了const axesHelper new THREE.AxesHelper(5); scene.add(axesHelper);坐标轴正常显示后再逐步排查物体、灯光和模型。4.2 模型加载失败或纹理丢失模型加载失败最典型的现象是控制台报了 404或者场景里只有乱七八糟的几何体但没有贴图。这通常跟资源路径有关。GLTF 文件内部会引用外部纹理图片加载器默认基于传入的 URL 目录去拼路径。如果你项目用的是 Vite需要把模型资源放到 public 目录下然后使用 /models/xxx.gltf 这种绝对路径而不是相对路径。另外要留意 glTF 的 variant 问题。有些模型文件是 PBR 格式shader 里用了金属度、粗糙度贴图如果你的 Three.js 版本比较旧可能不支持部分扩展。我建议把 Three.js 升到最新稳定版并且在加载后打印 gltf.parser 的信息能看出扩展加载情况。如果模型加载成功但显示出来是白色的多半是没有环境贴图。glTF 模型往往依靠环境光照才能体现反射效果。可以在场景里加一个简单的环境光或者设置 renderer.environment让模型有基本的明暗过渡。4.3 坐标与交互偏移问题坐标和交互偏移是另一个高频问题。最直接的表现是 鼠标点击物体时射线拿到的位置和视觉位置对不上。原因基本都在 NDC 转换那一套。你要检查两个地方 一是 canvas 的位置和尺寸。如果你的渲染器画布不是全屏而是处于某个容器内那 event.clientX 和 window.innerWidth 直接换算就会出错因为 canvas 相对于窗口的偏移没有被计算进去。解决方式是使用 renderer.domElement.getBoundingClientRect() 获取画布的实际边界然后再做坐标换算。二是相机的宽高比。当窗口 resize 时一定要同步更新相机的 aspect 和渲染器的尺寸window.addEventListener(resize, () { camera.aspect window.innerWidth / window.innerHeight; camera.updateProjectionMatrix(); renderer.setSize(window.innerWidth, window.innerHeight); });updateProjectionMatrix() 很多人会漏漏掉之后画面会变形交互坐标自然也对不上。我每次写 resize 都条件反射般把它带上这已经是肌肉记忆了。4.4 性能与掉帧优化清单如果场景已经跑起来了但帧率很低可以按这个清单逐项排查减少 draw call优先合并几何体把相同材质的 Mesh 丢进一个 Group 再合并。启用 renderer.shadowMap.enabled 时要注意阴影贴图的分辨率过大会严重影响性能一般 2048 就够。控制纹理尺寸大纹理用 texture.generateMipmaps 配合 anisotropy 设置不要每个材质都加载 4K 贴图。使用 Level of Detail 或者多层加载策略远处模型显示低模近处显示高模。清理不再使用的几何体、材质和纹理手动调用 dispose() 释放 GPU 内存。我在 t3code 的性能测试里发现一个简单的场景如果所有物体都是独立 Mesh不加任何优化100 个物体大约 100 次 draw call在低端手机上已经开始掉帧。合并之后同样数量降到 10 次以内帧率能稳定在 60fps。所以优化不是可选项而是 3D 项目上线前的必要环节。最后再分享一个小技巧 调试时在浏览器左上角打开 FPS 面板配合 Three.js 的 renderer.info能直观看到每次渲染调用了多少次 draw call、有多少个 Triangle。这个数据会告诉你瓶颈在哪。我每次调优都是先看 renderer.info.render.calls如果这个数字降不下来其他优化都是白费。t3code 走到现在最大的体会就是 3D 开发不要被复杂的原理吓倒先跑通一个最小闭环再往里面加效果。遇到问题先把场景里的角色拆开排查渲染器、相机、灯光、模型、交互一层一层看基本能解决九成的问题。后续我还会往 t3code 里加粒子系统、后处理和物理碰撞的示例如果你也做了类似的东西欢迎交流。