最近在折腾一个叫 t3code 的项目说是项目其实最初只是一个念头我想在浏览器里跑一个不依赖后端、打开页面就能看的 3D 场景能转、能缩放、能切换视角最好还能塞进几个自己建模的物件。市面上做 Web 3D 的方案不少但我最后选了 Three.js并且把整个工程命名为 t3code 作为代号。这篇文章就是把 t3code 从零到能跑的完整过程记录下来包括我踩过的坑、改过的参数和最后留下来的工程习惯。如果你正打算入门前端 3D或者已经写了几个 demo 但总感觉哪里没理顺这篇应该能帮你省掉不少摸索时间。1. 为什么我会做 t3code 这个项目从需求到选型1.1 初衷一个“纯粹”的 3D 展示页我当时的想法很具体不要后台、不要数据库、不要复杂的构建链路只要一个静态页面用户打开后能立刻看到一个可交互的 3D 场景。这个场景里要有地面、有主体物件、有灯光、有阴影最好还能用鼠标拖拽旋转滚动缩放。这个需求在企业官网、产品展示、数字孪生大屏、甚至个人作品集里都特别常见属于“看起来很炫但一旦做起来就全是细节”的那种任务。为什么强调“纯粹”因为很多团队一上来就上重型方案比如 Unity 的 WebGL 导出、或者用 react-three-fiber 这种基于 React 的封装然后引入一批状态管理、动画库。不是说这些方案不好而是对于一个以展示为主、不需要复杂业务逻辑的场景直接把 Three.js 当作核心库、其他东西按需引入反而更可控。t3code 这个项目就是在这种思路下立项的保持最小依赖保持最大掌控力。1.2 技术方案对比为什么不是 Unity、不是 R3F我简单做了一轮对比。Unity 导出的 WebGL 包体积大加载慢而且场景里的交互逻辑被封装得很深想改一个细节得回 Unity 编辑器重新导一次。R3Freact-three-fiber本身很好用但对团队有 React 经验的要求而且它的声明式写法会让初学者觉得“我好像没写 Three.js”一旦遇到报错排查链路直接被拉长。原生 Three.js 的好处是概念清晰场景、相机、渲染器、物体、灯光、材质每一层都能直接理解和控制。坏处是样板代码多一点但这点样板代码恰恰是理解 Web 3D 底层逻辑最划算的学费。所以 t3code 最终的技术栈是Vite TypeScript Three.js。Vite 负责开发服务器和构建TypeScript 负责类型约束Three.js 负责 3D 渲染。没有其他花哨的东西。1.3 项目目录结构一开始就分好层我见过太多 Three.js 项目写着写着就变成一个巨大的 app.ts所有代码堆在一起。t3code 从第一天就按职责分了目录后期加功能特别顺手。t3code/ ├─ index.html ├─ package.json ├─ tsconfig.json ├─ vite.config.ts └─ src/ ├─ main.ts # 入口负责初始化场景 ├─ scene/ │ ├─ createScene.ts # 创建场景 │ ├─ createCamera.ts # 创建相机 │ └─ createRenderer.ts # 创建渲染器 ├─ objects/ │ ├─ ground.ts # 地面 │ └─ mainCube.ts # 主物体 ├─ lights/ │ └─ setupLights.ts # 灯光配置 └─ systems/ ├─ loop.ts # 动画循环 └─ resize.ts # 窗口自适应这样一个目录结构带来的直接好处是想改灯光的时候不用在几千行代码里找想换物体的时候直接改 objects 目录。后面我会按照这个结构一步步带大家把每个文件填满。2. 环境准备与工程化搭建Vite 是最省心的起点2.1 初始化 Vite TypeScript 工程t3code 的项目初始化我用的是 Vite 官方命令行工具。打开终端执行下面的命令npm create vitelatest t3code -- --template vanilla-ts这个命令会创建一个基于 TypeScript 的 Vite 模板里面带有 tsconfig.json 和基本的目录结构。我特意没用 Vue 或 React 模板因为 t3code 不需要框架层用框架模板反而会引入一堆用不到的东西。创建完以后进入目录安装 Three.jscd t3code npm install three这里有一点需要说明新版 Three.js 已经内置了 TypeScript 类型声明所以不需要额外安装 types/three。如果你在网上搜到老教程让你装 types/three多半是因为版本较旧。装完以后可以打开 package.json 确认一下 three 的版本号t3code 做的时候是 0.1xx 版本API 已经相当稳定。2.2 跑通第一个渲染窗口三角形比立方体更合适很多人入门 Three.js 的第一反应是创建一个立方体但我建议先画一个三角形。为什么因为三角形是 WebGL 的最小单元立方体本质上也是由三角形组成的。能看到三角形在屏幕上出现说明整个渲染链路已经通了后面的东西都是在这个基础上堆叠。先清空 src/main.ts写入最基础的代码import * as THREE from three; const scene new THREE.Scene(); const camera new THREE.PerspectiveCamera( 75, window.innerWidth / window.innerHeight, 0.1, 1000 ); const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(window.innerWidth, window.innerHeight); document.body.appendChild(renderer.domElement); const geometry new THREE.BufferGeometry(); const vertices new Float32Array([ 0, 0, 0, 1, 0, 0, 0, 1, 0 ]); geometry.setAttribute(position, new THREE.BufferAttribute(vertices, 3)); const material new THREE.MeshBasicMaterial({ color: 0x3b82f6 }); const triangle new THREE.Mesh(geometry, material); scene.add(triangle); camera.position.z 3; function animate() { requestAnimationFrame(animate); renderer.render(scene, camera); } animate();然后在项目根目录执行npm run dev浏览器打开 Vite 给出的本地地址如果能看到一个蓝色三角形恭喜你t3code 的第一步已经踩实了。这里我不急着加轨道控制先把基础链路看清楚再一步步往上加东西。2.3 开发服务器与构建输出习惯比命令更重要Vite 的开发服务器有热更新改代码以后页面自动刷新。这很爽但有个习惯要养成改完代码以后瞄一眼浏览器控制台有没有报错。Three.js 很多错误是运行时才能发现的比如几何体属性缺失、材质参数类型不对这些不一定在编辑器中爆红但控制台一定会输出警告。把这些警告当回事能省下后面大量的排查时间。构建方面直接npm run buildVite 会输出到 dist 目录。如果后续要部署到服务器需要留意一点静态资源路径。默认 Vite 的 base 是/如果你把 t3code 部署在子路径下比如https://example.com/t3code/就要在 vite.config.ts 里设置 baseimport { defineConfig } from vite; export default defineConfig({ base: ./ });用相对路径是静态展示页最稳妥的方案丢到哪个目录都能跑。3. 场景、相机与渲染器先把“铁三角”搞清楚3.1 Scene所有物体的容器Three.js 里的 Scene 本质上就是一个容器所有可见的、不可见的物体都挂在它下面。它的核心能力是层级管理你可以把多个物体放进一个 Group再把 Group 加进 Scene。对 Group 做变换时里面的物体会跟着一起动就像文件夹管理文件一样。t3code 里我用createScene.ts单独管理场景的创建import * as THREE from three; export function createScene(): THREE.Scene { const scene new THREE.Scene(); // 背景色很重要决定了整个页面的氛围 scene.background new THREE.Color(0x0b0b0f); return scene; }背景色这里我用了一个接近黑的深色目的是让后面加的暖色灯光更有对比感。如果你做的是白天场景用 0x87ceeb 之类浅色会有完全不同的观感。Scene 本身还能添加雾效通过scene.fog new THREE.Fog(0x0b0b0f, 10, 50)可以让远处的物体渐渐隐入背景色质感和层次感一下就出来了。3.2 Camera透视相机与正交相机的取舍t3code 默认使用 PerspectiveCamera透视相机这是最符合人眼直觉的相机近大远小最适合产品展示和场景漫游。初始化时四个参数需要理解透彻fov视野角度用角度值表示比如 75 代表垂直方向能看到 75 度范围内的场景。数值越大看到的东西越多但透视变形也越强容易产生“鱼眼感”。aspect宽高比等于画布宽度除以高度一般设置为window.innerWidth / window.innerHeight。near 和 far近裁剪面和远裁剪面相机只能看到这两个距离之间的物体。near 太小会导致深度精度问题far 太大又容易引发闪烁常规场景 near 用 0.1、far 用 100 就够。这里有一个很重要但新手容易忽略的点改完相机位置后需要调用camera.lookAt()指定相机朝向。Three.js 的相机默认看向 Z 轴负方向如果你把相机放在 (0, 0, 5) 而物体在原点默认是能看到的但如果你把相机挪到侧面比如 (5, 3, 5)不调用 lookAt 时画面里可能什么都看不到。3.3 Renderer画布尺寸、像素比和动画循环Renderer 是整个渲染过程的总调度。t3code 里我这样创建渲染器import * as THREE from three; export function createRenderer(): THREE.WebGLRenderer { const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(window.innerWidth, window.innerHeight); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); renderer.shadowMap.enabled true; renderer.shadowMap.type THREE.PCFSoftShadowMap; document.body.appendChild(renderer.domElement); return renderer; }有几个细节值得说。setPixelRatio是为了适配 Retina 屏幕。如果你不设置在高分屏上渲染结果会发虚如果直接设置成window.devicePixelRatio超过 2 的屏幕会带来多余的 GPU 开销。取Math.min(devicePixelRatio, 2)是一个性能和清晰度的平衡点也是 Three.js 官方示例里的常见做法。shadowMap开关是阴影的关键。Three.js 默认不开启阴影必须把shadowMap.enabled置为 true然后再配合灯光和物体的 castShadow/receiveShadow 属性才能真正出阴影。我习惯用PCFSoftShadowMap柔和的边缘比硬阴影好看太多。动画循环我用requestAnimationFrame实现。它会在浏览器每次重绘前执行回调帧率通常 60fps到高刷屏上可能更高。所有需要变化的元素比如物体旋转、相机移动、光照强度变化都应该放在这个回调内部function animate() { requestAnimationFrame(animate); // 在这里更新物体的状态 renderer.render(scene, camera); }一个很容易犯的错误是把动画循环写成了setInterval(render, 16.7)这样在高刷屏上会掉帧在低帧率设备上又会卡顿。requestAnimationFrame是浏览器层面的最优调度没有理由不用它。4. 模型、材质与光照让 t3code 真正“看得见”4.1 用几何体和材质搭出基础物件三角形能跑通渲染链路但离“作品”还很远。t3code 的第一个正式场景里我放了一个立方体作为主视觉再加一个圆环作为点缀。选立方体是因为它的明暗关系最容易观察每个面朝向不同接受光照后的亮度差异会非常明显很适合用来调光和调材质。创建主物体的代码放在mainCube.ts里import * as THREE from three; export function createMainCube(): THREE.Mesh { const geometry new THREE.BoxGeometry(1.5, 1.5, 1.5); const material new THREE.MeshStandardMaterial({ color: 0xff7043, roughness: 0.35, metalness: 0.05 }); const cube new THREE.Mesh(geometry, material); cube.position.set(0, 1, 0); cube.castShadow true; cube.receiveShadow true; return cube; }MeshStandardMaterial是 Three.js 里最常用的 PBR 材质可以理解为“基于物理的渲染”。和基础材质MeshBasicMaterial的区别是基本材质完全不受光照影响像一张直接贴上去的贴纸标准材质则需要有光才能看见roughness 控制粗糙度值越大表面越糙高光越散metalness 控制金属感值越大物体越像金属。这个材质在暗场景里的质感比 Basic 好太多了代价只是多一点计算量现代设备完全扛得住。圆环可以用来摆姿态或者做环状结构t3code 里我用它做了一个半透明的环绕装饰const ringGeometry new THREE.TorusGeometry(2, 0.08, 16, 100); const ringMaterial new THREE.MeshStandardMaterial({ color: 0x64b5f6, roughness: 0.5, metalness: 0.8, transparent: true, opacity: 0.6 }); const ring new THREE.Mesh(ringGeometry, ringMaterial); ring.rotation.x Math.PI / 2; ring.position.y 1;透明材质在 Three.js 里要注意渲染顺序问题不过 t3code 这个场景简单透明度不高暂时没有出现遮挡错乱。后面如果要做复杂透明材质可能要考虑depthWrite的设置这里先不展开。4.2 光的种类与布光逻辑没有光的场景PBR 材质会显示为纯黑所以在 t3code 里我把灯光当作与建模同等重要的环节来对待。我使用了两个主光源加一个环境光import * as THREE from three; export function setupLights(scene: THREE.Scene): void { // 环境光保证物体的暗面不至于完全漆黑 const ambient new THREE.AmbientLight(0x404060, 0.6); scene.add(ambient); // 主光源平行光模拟太阳产生明显的明暗交界 const mainLight new THREE.DirectionalLight(0xffedcc, 1.2); mainLight.position.set(5, 8, 5); mainLight.castShadow true; scene.add(mainLight); // 补光点光源放在主光的对侧把阴影里的细节拉出来 const fillLight new THREE.PointLight(0x6688ff, 0.5); fillLight.position.set(-3, 2, -4); scene.add(fillLight); }这里选择的DirectionalLight没有位置的概念只有方向的概念所以在设置 position 以后它只是把光线从该位置指向原点。平行光的特点是光线彼此平行照出来的阴影边界干净非常适合做场景的主光源。PointLight则像一个灯泡从中心向四周发射光线适合做局部的补光。t3code 第一天跑到这里时我盯着屏幕看了一会儿觉得“好像有点东西了”。主光把立方体的右上角打得发白蓝色的补光在暗部泛起一层冷色半透的圆环横在立方体上方整张画面的层次感一下子出来了。这种实时的反馈既直观也挑人参数调得不对比如主光强度调成 5画面会瞬间过曝白花花的一片什么都看不清。所以调光的时候养成习惯改一个变量保存刷新不要一口气改五六个参数然后一脸茫然。4.3 OrbitControls让画面动起来静态渲染图做得再好也不是 Web 3D 的卖点。交互才是。t3code 里我引入了 OrbitControls也就是轨道控制器让用户能自由旋转和缩放视角。它的引入方式比较特殊不通过 npm 包安装而是从 three 的附加模块导入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; controls.target.set(0, 1, 0);这里最值得说的是enableDamping。如果不开它拖拽结束的那一刻画面就停住手感非常生硬开了之后视角会有惯性缓冲平滑地滑向停止位置。你需要在动画循环里加上controls.update()阻尼效果才会生效不然没有用。我还限制了相机与目标点的距离范围避免用户缩到物体里面去或者缩得太远导致场景变得极小而找不到。target.set(0, 1, 0)和主物体的位置一致这样一进场景相机就会自动看向主物体。5. 踩坑记录开发 t3code 时真实的翻车瞬间5.1 物体“消失”了FOV 和相机距离的关系t3code 开发到一半时我把主立方体的尺寸从 1.5 改到 0.2然后刷新发现画面里什么都看不到了。第一反应是代码哪里写错了检查半天没发现问题。后来把相机距离从 5 改成 1物体又出现了。原因其实很简单PerspectiveCamera 的 FOV 是 75相机在 Z 轴 5 的位置物体只有 0.2 大小在屏幕上只占不到几个像素加上背景是深色自然就“看不见”了。这不是渲染错误是视觉误差。这个坑给我的教训是在调整物体尺寸的时候要意识到相机视野和距离是一个整体系统。不会有一个参数能独立适配所有情况。反过来如果你把物体做得很大相机离得很近又会出现“物体把整个画面撑满甚至穿模到相机后面”的情况。此时要么拉远相机要么缩小物体没有捷径。5.2 纹理加载失败路径与跨域有一次我想给立方体贴一张木纹纹理用TextureLoader从本地加载图片结果控制台报错纹理显示为一片紫色。排查后发现是路径问题。Vite 开发服务器中如果你把图片放在public目录下路径要以/开头引用比如/textures/wood.jpg如果你放在src/assets里则要用 import 导入让 Vite 处理路径。新手最容易犯的错是放到了 src 里还用字符串路径去找结果找不到文件。如果是从 CDN 加载纹理还需要考虑跨域问题。Three.js 的 TextureLoader 基于网页的图片加载机制如果图片服务器没有允许跨域的头信息加载会失败。解决办法有几种让服务端加上 CORS 响应头或者把图片下载到本地再打包。t3code 里为了避免这种麻烦所有纹理都走本地目录。5.3 动画循环与内存泄漏不断 add 却没有 remove还有一个比较隐蔽的坑有些物体或纹理在使用完之后没有释放内存。WebGL 的内存管理和普通 JavaScript 不太一样它需要显式地调用geometry.dispose()和material.dispose()来告诉 GPU 这些资源可以回收了。我在 t3code 里做过一个实验每秒钟向场景里添加一个新的随机颜色小球持续几分钟后页面开始卡顿。排查发现虽然小球是随机删除的但删除的时候只从 scene 里移除没有调用 dispose导致 GPU 上的缓冲区和纹理一直残留。虽然这个实验是为了测试但真实项目里做动态生成物体时同样的逻辑错误也一样会发生。正确的删除方式应该是function removeObject(obj: THREE.Mesh) { scene.remove(obj); obj.geometry.dispose(); (obj.material as THREE.Material).dispose(); }别小看这三行代码动态场景和长期运行的页面里它决定了你跑半小时之后是丝般顺滑还是卡成幻灯片。6. 性能优化与扩展思路跑通后还能怎么玩6.1 静态资源异步加载与加载管理器t3code 看似静态但模型、贴图都是资源。页面刚打开时如果一次性加载十几个大模型白屏时间会相当感人。Three.js 提供了 GLTFLoader 加载外部模型的方案同时有LoadingManager可以跟踪加载进度做出加载百分比提示。一个比较实用的懒加载思路是这样先用很轻量的示意几何体把场景占位渲染出来等用户交互或进入特定区域时再去加载真正的精细模型。这个方案在很多 3D 展示页里都有应用t3code 后续升级也可以走这条路。Vite 自带按需加载能力配合动态 import可以做到点击按钮才加载某个模块的代码和关联资产。这样初始 bundle 体积可以压得很低加载策略也会干净很多。6.2 帧率监控与最小化重绘开发过程中我习惯在页面上显示实时帧率用来快速判断场景的渲染开销。做法很简单在动画循环里累加帧数每秒钟计算一次 FPSlet frameCount 0; let lastTime performance.now(); function loop() { requestAnimationFrame(loop); frameCount; const now performance.now(); if (now - lastTime 1000) { console.log(FPS:, frameCount); frameCount 0; lastTime now; } renderer.render(scene, camera); }如果帧率长期低于 30就要考虑优化了降低setPixelRatio、减少 shadowMap 的纹理大小、合并几何体、或者用 LODLevel of Detail根据距离切换不同精度的模型方案。t3code 目前的场景物体数量少帧率很稳定但这个监控逻辑我始终保留着后面每加一个新物件我都能第一眼看出它对性能的影响。6.3 模型导入、动画、后期处理的扩展方向跑通基础功能以后t3code 的扩展空间其实很大。最重要的方向是用 GLTFLoader 导入真正建模软件做的模型Blender 里建一棵树或者一个机器人导出为 glb 格式后放到 public/models 目录然后import { GLTFLoader } from three/examples/jsm/loaders/GLTFLoader.js; const loader new GLTFLoader(); loader.load(/models/robot.glb, (gltf) { scene.add(gltf.scene); }, undefined, (err) { console.error(模型加载失败, err); });有了外部模型场景的真实感会立刻提升一个档次。配合动画系统可以做模型的肢体摆动、机械臂旋转。后期处理方面Three.js 的 EffectComposer 支持添加 Bloom 辉光、Film 噪点、Vignette 暗角等效果把 3D 场景的视觉氛围再往上推一层。我自己在实际操作中的体会是Web 3D 项目最怕的不是不会用某个 API而是没有一个清晰的项目骨架。t3code 之所以能顺利跑下来很大程度上是因为我把场景、相机、渲染器、物体、灯光、循环这些事情从一开始就拆开了。等你把这些基础单元都熟练了后面再上模型、动画、后期处理都是在同样的骨架上做加法不会出现“加一个新功能就重构一遍”的窘境。如果你也要起一个自己的 3D 项目建议不要急着堆功能先把这套骨架搭稳。
最近在折腾一个叫 t3code 的项目说是项目其实最初只是一个念头我想在浏览器里跑一个不依赖后端、打开页面就能看的 3D 场景能转、能缩放、能切换视角最好还能塞进几个自己建模的物件。市面上做 Web 3D 的方案不少但我最后选了 Three.js并且把整个工程命名为 t3code 作为代号。这篇文章就是把 t3code 从零到能跑的完整过程记录下来包括我踩过的坑、改过的参数和最后留下来的工程习惯。如果你正打算入门前端 3D或者已经写了几个 demo 但总感觉哪里没理顺这篇应该能帮你省掉不少摸索时间。1. 为什么我会做 t3code 这个项目从需求到选型1.1 初衷一个“纯粹”的 3D 展示页我当时的想法很具体不要后台、不要数据库、不要复杂的构建链路只要一个静态页面用户打开后能立刻看到一个可交互的 3D 场景。这个场景里要有地面、有主体物件、有灯光、有阴影最好还能用鼠标拖拽旋转滚动缩放。这个需求在企业官网、产品展示、数字孪生大屏、甚至个人作品集里都特别常见属于“看起来很炫但一旦做起来就全是细节”的那种任务。为什么强调“纯粹”因为很多团队一上来就上重型方案比如 Unity 的 WebGL 导出、或者用 react-three-fiber 这种基于 React 的封装然后引入一批状态管理、动画库。不是说这些方案不好而是对于一个以展示为主、不需要复杂业务逻辑的场景直接把 Three.js 当作核心库、其他东西按需引入反而更可控。t3code 这个项目就是在这种思路下立项的保持最小依赖保持最大掌控力。1.2 技术方案对比为什么不是 Unity、不是 R3F我简单做了一轮对比。Unity 导出的 WebGL 包体积大加载慢而且场景里的交互逻辑被封装得很深想改一个细节得回 Unity 编辑器重新导一次。R3Freact-three-fiber本身很好用但对团队有 React 经验的要求而且它的声明式写法会让初学者觉得“我好像没写 Three.js”一旦遇到报错排查链路直接被拉长。原生 Three.js 的好处是概念清晰场景、相机、渲染器、物体、灯光、材质每一层都能直接理解和控制。坏处是样板代码多一点但这点样板代码恰恰是理解 Web 3D 底层逻辑最划算的学费。所以 t3code 最终的技术栈是Vite TypeScript Three.js。Vite 负责开发服务器和构建TypeScript 负责类型约束Three.js 负责 3D 渲染。没有其他花哨的东西。1.3 项目目录结构一开始就分好层我见过太多 Three.js 项目写着写着就变成一个巨大的 app.ts所有代码堆在一起。t3code 从第一天就按职责分了目录后期加功能特别顺手。t3code/ ├─ index.html ├─ package.json ├─ tsconfig.json ├─ vite.config.ts └─ src/ ├─ main.ts # 入口负责初始化场景 ├─ scene/ │ ├─ createScene.ts # 创建场景 │ ├─ createCamera.ts # 创建相机 │ └─ createRenderer.ts # 创建渲染器 ├─ objects/ │ ├─ ground.ts # 地面 │ └─ mainCube.ts # 主物体 ├─ lights/ │ └─ setupLights.ts # 灯光配置 └─ systems/ ├─ loop.ts # 动画循环 └─ resize.ts # 窗口自适应这样一个目录结构带来的直接好处是想改灯光的时候不用在几千行代码里找想换物体的时候直接改 objects 目录。后面我会按照这个结构一步步带大家把每个文件填满。2. 环境准备与工程化搭建Vite 是最省心的起点2.1 初始化 Vite TypeScript 工程t3code 的项目初始化我用的是 Vite 官方命令行工具。打开终端执行下面的命令npm create vitelatest t3code -- --template vanilla-ts这个命令会创建一个基于 TypeScript 的 Vite 模板里面带有 tsconfig.json 和基本的目录结构。我特意没用 Vue 或 React 模板因为 t3code 不需要框架层用框架模板反而会引入一堆用不到的东西。创建完以后进入目录安装 Three.jscd t3code npm install three这里有一点需要说明新版 Three.js 已经内置了 TypeScript 类型声明所以不需要额外安装 types/three。如果你在网上搜到老教程让你装 types/three多半是因为版本较旧。装完以后可以打开 package.json 确认一下 three 的版本号t3code 做的时候是 0.1xx 版本API 已经相当稳定。2.2 跑通第一个渲染窗口三角形比立方体更合适很多人入门 Three.js 的第一反应是创建一个立方体但我建议先画一个三角形。为什么因为三角形是 WebGL 的最小单元立方体本质上也是由三角形组成的。能看到三角形在屏幕上出现说明整个渲染链路已经通了后面的东西都是在这个基础上堆叠。先清空 src/main.ts写入最基础的代码import * as THREE from three; const scene new THREE.Scene(); const camera new THREE.PerspectiveCamera( 75, window.innerWidth / window.innerHeight, 0.1, 1000 ); const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(window.innerWidth, window.innerHeight); document.body.appendChild(renderer.domElement); const geometry new THREE.BufferGeometry(); const vertices new Float32Array([ 0, 0, 0, 1, 0, 0, 0, 1, 0 ]); geometry.setAttribute(position, new THREE.BufferAttribute(vertices, 3)); const material new THREE.MeshBasicMaterial({ color: 0x3b82f6 }); const triangle new THREE.Mesh(geometry, material); scene.add(triangle); camera.position.z 3; function animate() { requestAnimationFrame(animate); renderer.render(scene, camera); } animate();然后在项目根目录执行npm run dev浏览器打开 Vite 给出的本地地址如果能看到一个蓝色三角形恭喜你t3code 的第一步已经踩实了。这里我不急着加轨道控制先把基础链路看清楚再一步步往上加东西。2.3 开发服务器与构建输出习惯比命令更重要Vite 的开发服务器有热更新改代码以后页面自动刷新。这很爽但有个习惯要养成改完代码以后瞄一眼浏览器控制台有没有报错。Three.js 很多错误是运行时才能发现的比如几何体属性缺失、材质参数类型不对这些不一定在编辑器中爆红但控制台一定会输出警告。把这些警告当回事能省下后面大量的排查时间。构建方面直接npm run buildVite 会输出到 dist 目录。如果后续要部署到服务器需要留意一点静态资源路径。默认 Vite 的 base 是/如果你把 t3code 部署在子路径下比如https://example.com/t3code/就要在 vite.config.ts 里设置 baseimport { defineConfig } from vite; export default defineConfig({ base: ./ });用相对路径是静态展示页最稳妥的方案丢到哪个目录都能跑。3. 场景、相机与渲染器先把“铁三角”搞清楚3.1 Scene所有物体的容器Three.js 里的 Scene 本质上就是一个容器所有可见的、不可见的物体都挂在它下面。它的核心能力是层级管理你可以把多个物体放进一个 Group再把 Group 加进 Scene。对 Group 做变换时里面的物体会跟着一起动就像文件夹管理文件一样。t3code 里我用createScene.ts单独管理场景的创建import * as THREE from three; export function createScene(): THREE.Scene { const scene new THREE.Scene(); // 背景色很重要决定了整个页面的氛围 scene.background new THREE.Color(0x0b0b0f); return scene; }背景色这里我用了一个接近黑的深色目的是让后面加的暖色灯光更有对比感。如果你做的是白天场景用 0x87ceeb 之类浅色会有完全不同的观感。Scene 本身还能添加雾效通过scene.fog new THREE.Fog(0x0b0b0f, 10, 50)可以让远处的物体渐渐隐入背景色质感和层次感一下就出来了。3.2 Camera透视相机与正交相机的取舍t3code 默认使用 PerspectiveCamera透视相机这是最符合人眼直觉的相机近大远小最适合产品展示和场景漫游。初始化时四个参数需要理解透彻fov视野角度用角度值表示比如 75 代表垂直方向能看到 75 度范围内的场景。数值越大看到的东西越多但透视变形也越强容易产生“鱼眼感”。aspect宽高比等于画布宽度除以高度一般设置为window.innerWidth / window.innerHeight。near 和 far近裁剪面和远裁剪面相机只能看到这两个距离之间的物体。near 太小会导致深度精度问题far 太大又容易引发闪烁常规场景 near 用 0.1、far 用 100 就够。这里有一个很重要但新手容易忽略的点改完相机位置后需要调用camera.lookAt()指定相机朝向。Three.js 的相机默认看向 Z 轴负方向如果你把相机放在 (0, 0, 5) 而物体在原点默认是能看到的但如果你把相机挪到侧面比如 (5, 3, 5)不调用 lookAt 时画面里可能什么都看不到。3.3 Renderer画布尺寸、像素比和动画循环Renderer 是整个渲染过程的总调度。t3code 里我这样创建渲染器import * as THREE from three; export function createRenderer(): THREE.WebGLRenderer { const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(window.innerWidth, window.innerHeight); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); renderer.shadowMap.enabled true; renderer.shadowMap.type THREE.PCFSoftShadowMap; document.body.appendChild(renderer.domElement); return renderer; }有几个细节值得说。setPixelRatio是为了适配 Retina 屏幕。如果你不设置在高分屏上渲染结果会发虚如果直接设置成window.devicePixelRatio超过 2 的屏幕会带来多余的 GPU 开销。取Math.min(devicePixelRatio, 2)是一个性能和清晰度的平衡点也是 Three.js 官方示例里的常见做法。shadowMap开关是阴影的关键。Three.js 默认不开启阴影必须把shadowMap.enabled置为 true然后再配合灯光和物体的 castShadow/receiveShadow 属性才能真正出阴影。我习惯用PCFSoftShadowMap柔和的边缘比硬阴影好看太多。动画循环我用requestAnimationFrame实现。它会在浏览器每次重绘前执行回调帧率通常 60fps到高刷屏上可能更高。所有需要变化的元素比如物体旋转、相机移动、光照强度变化都应该放在这个回调内部function animate() { requestAnimationFrame(animate); // 在这里更新物体的状态 renderer.render(scene, camera); }一个很容易犯的错误是把动画循环写成了setInterval(render, 16.7)这样在高刷屏上会掉帧在低帧率设备上又会卡顿。requestAnimationFrame是浏览器层面的最优调度没有理由不用它。4. 模型、材质与光照让 t3code 真正“看得见”4.1 用几何体和材质搭出基础物件三角形能跑通渲染链路但离“作品”还很远。t3code 的第一个正式场景里我放了一个立方体作为主视觉再加一个圆环作为点缀。选立方体是因为它的明暗关系最容易观察每个面朝向不同接受光照后的亮度差异会非常明显很适合用来调光和调材质。创建主物体的代码放在mainCube.ts里import * as THREE from three; export function createMainCube(): THREE.Mesh { const geometry new THREE.BoxGeometry(1.5, 1.5, 1.5); const material new THREE.MeshStandardMaterial({ color: 0xff7043, roughness: 0.35, metalness: 0.05 }); const cube new THREE.Mesh(geometry, material); cube.position.set(0, 1, 0); cube.castShadow true; cube.receiveShadow true; return cube; }MeshStandardMaterial是 Three.js 里最常用的 PBR 材质可以理解为“基于物理的渲染”。和基础材质MeshBasicMaterial的区别是基本材质完全不受光照影响像一张直接贴上去的贴纸标准材质则需要有光才能看见roughness 控制粗糙度值越大表面越糙高光越散metalness 控制金属感值越大物体越像金属。这个材质在暗场景里的质感比 Basic 好太多了代价只是多一点计算量现代设备完全扛得住。圆环可以用来摆姿态或者做环状结构t3code 里我用它做了一个半透明的环绕装饰const ringGeometry new THREE.TorusGeometry(2, 0.08, 16, 100); const ringMaterial new THREE.MeshStandardMaterial({ color: 0x64b5f6, roughness: 0.5, metalness: 0.8, transparent: true, opacity: 0.6 }); const ring new THREE.Mesh(ringGeometry, ringMaterial); ring.rotation.x Math.PI / 2; ring.position.y 1;透明材质在 Three.js 里要注意渲染顺序问题不过 t3code 这个场景简单透明度不高暂时没有出现遮挡错乱。后面如果要做复杂透明材质可能要考虑depthWrite的设置这里先不展开。4.2 光的种类与布光逻辑没有光的场景PBR 材质会显示为纯黑所以在 t3code 里我把灯光当作与建模同等重要的环节来对待。我使用了两个主光源加一个环境光import * as THREE from three; export function setupLights(scene: THREE.Scene): void { // 环境光保证物体的暗面不至于完全漆黑 const ambient new THREE.AmbientLight(0x404060, 0.6); scene.add(ambient); // 主光源平行光模拟太阳产生明显的明暗交界 const mainLight new THREE.DirectionalLight(0xffedcc, 1.2); mainLight.position.set(5, 8, 5); mainLight.castShadow true; scene.add(mainLight); // 补光点光源放在主光的对侧把阴影里的细节拉出来 const fillLight new THREE.PointLight(0x6688ff, 0.5); fillLight.position.set(-3, 2, -4); scene.add(fillLight); }这里选择的DirectionalLight没有位置的概念只有方向的概念所以在设置 position 以后它只是把光线从该位置指向原点。平行光的特点是光线彼此平行照出来的阴影边界干净非常适合做场景的主光源。PointLight则像一个灯泡从中心向四周发射光线适合做局部的补光。t3code 第一天跑到这里时我盯着屏幕看了一会儿觉得“好像有点东西了”。主光把立方体的右上角打得发白蓝色的补光在暗部泛起一层冷色半透的圆环横在立方体上方整张画面的层次感一下子出来了。这种实时的反馈既直观也挑人参数调得不对比如主光强度调成 5画面会瞬间过曝白花花的一片什么都看不清。所以调光的时候养成习惯改一个变量保存刷新不要一口气改五六个参数然后一脸茫然。4.3 OrbitControls让画面动起来静态渲染图做得再好也不是 Web 3D 的卖点。交互才是。t3code 里我引入了 OrbitControls也就是轨道控制器让用户能自由旋转和缩放视角。它的引入方式比较特殊不通过 npm 包安装而是从 three 的附加模块导入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; controls.target.set(0, 1, 0);这里最值得说的是enableDamping。如果不开它拖拽结束的那一刻画面就停住手感非常生硬开了之后视角会有惯性缓冲平滑地滑向停止位置。你需要在动画循环里加上controls.update()阻尼效果才会生效不然没有用。我还限制了相机与目标点的距离范围避免用户缩到物体里面去或者缩得太远导致场景变得极小而找不到。target.set(0, 1, 0)和主物体的位置一致这样一进场景相机就会自动看向主物体。5. 踩坑记录开发 t3code 时真实的翻车瞬间5.1 物体“消失”了FOV 和相机距离的关系t3code 开发到一半时我把主立方体的尺寸从 1.5 改到 0.2然后刷新发现画面里什么都看不到了。第一反应是代码哪里写错了检查半天没发现问题。后来把相机距离从 5 改成 1物体又出现了。原因其实很简单PerspectiveCamera 的 FOV 是 75相机在 Z 轴 5 的位置物体只有 0.2 大小在屏幕上只占不到几个像素加上背景是深色自然就“看不见”了。这不是渲染错误是视觉误差。这个坑给我的教训是在调整物体尺寸的时候要意识到相机视野和距离是一个整体系统。不会有一个参数能独立适配所有情况。反过来如果你把物体做得很大相机离得很近又会出现“物体把整个画面撑满甚至穿模到相机后面”的情况。此时要么拉远相机要么缩小物体没有捷径。5.2 纹理加载失败路径与跨域有一次我想给立方体贴一张木纹纹理用TextureLoader从本地加载图片结果控制台报错纹理显示为一片紫色。排查后发现是路径问题。Vite 开发服务器中如果你把图片放在public目录下路径要以/开头引用比如/textures/wood.jpg如果你放在src/assets里则要用 import 导入让 Vite 处理路径。新手最容易犯的错是放到了 src 里还用字符串路径去找结果找不到文件。如果是从 CDN 加载纹理还需要考虑跨域问题。Three.js 的 TextureLoader 基于网页的图片加载机制如果图片服务器没有允许跨域的头信息加载会失败。解决办法有几种让服务端加上 CORS 响应头或者把图片下载到本地再打包。t3code 里为了避免这种麻烦所有纹理都走本地目录。5.3 动画循环与内存泄漏不断 add 却没有 remove还有一个比较隐蔽的坑有些物体或纹理在使用完之后没有释放内存。WebGL 的内存管理和普通 JavaScript 不太一样它需要显式地调用geometry.dispose()和material.dispose()来告诉 GPU 这些资源可以回收了。我在 t3code 里做过一个实验每秒钟向场景里添加一个新的随机颜色小球持续几分钟后页面开始卡顿。排查发现虽然小球是随机删除的但删除的时候只从 scene 里移除没有调用 dispose导致 GPU 上的缓冲区和纹理一直残留。虽然这个实验是为了测试但真实项目里做动态生成物体时同样的逻辑错误也一样会发生。正确的删除方式应该是function removeObject(obj: THREE.Mesh) { scene.remove(obj); obj.geometry.dispose(); (obj.material as THREE.Material).dispose(); }别小看这三行代码动态场景和长期运行的页面里它决定了你跑半小时之后是丝般顺滑还是卡成幻灯片。6. 性能优化与扩展思路跑通后还能怎么玩6.1 静态资源异步加载与加载管理器t3code 看似静态但模型、贴图都是资源。页面刚打开时如果一次性加载十几个大模型白屏时间会相当感人。Three.js 提供了 GLTFLoader 加载外部模型的方案同时有LoadingManager可以跟踪加载进度做出加载百分比提示。一个比较实用的懒加载思路是这样先用很轻量的示意几何体把场景占位渲染出来等用户交互或进入特定区域时再去加载真正的精细模型。这个方案在很多 3D 展示页里都有应用t3code 后续升级也可以走这条路。Vite 自带按需加载能力配合动态 import可以做到点击按钮才加载某个模块的代码和关联资产。这样初始 bundle 体积可以压得很低加载策略也会干净很多。6.2 帧率监控与最小化重绘开发过程中我习惯在页面上显示实时帧率用来快速判断场景的渲染开销。做法很简单在动画循环里累加帧数每秒钟计算一次 FPSlet frameCount 0; let lastTime performance.now(); function loop() { requestAnimationFrame(loop); frameCount; const now performance.now(); if (now - lastTime 1000) { console.log(FPS:, frameCount); frameCount 0; lastTime now; } renderer.render(scene, camera); }如果帧率长期低于 30就要考虑优化了降低setPixelRatio、减少 shadowMap 的纹理大小、合并几何体、或者用 LODLevel of Detail根据距离切换不同精度的模型方案。t3code 目前的场景物体数量少帧率很稳定但这个监控逻辑我始终保留着后面每加一个新物件我都能第一眼看出它对性能的影响。6.3 模型导入、动画、后期处理的扩展方向跑通基础功能以后t3code 的扩展空间其实很大。最重要的方向是用 GLTFLoader 导入真正建模软件做的模型Blender 里建一棵树或者一个机器人导出为 glb 格式后放到 public/models 目录然后import { GLTFLoader } from three/examples/jsm/loaders/GLTFLoader.js; const loader new GLTFLoader(); loader.load(/models/robot.glb, (gltf) { scene.add(gltf.scene); }, undefined, (err) { console.error(模型加载失败, err); });有了外部模型场景的真实感会立刻提升一个档次。配合动画系统可以做模型的肢体摆动、机械臂旋转。后期处理方面Three.js 的 EffectComposer 支持添加 Bloom 辉光、Film 噪点、Vignette 暗角等效果把 3D 场景的视觉氛围再往上推一层。我自己在实际操作中的体会是Web 3D 项目最怕的不是不会用某个 API而是没有一个清晰的项目骨架。t3code 之所以能顺利跑下来很大程度上是因为我把场景、相机、渲染器、物体、灯光、循环这些事情从一开始就拆开了。等你把这些基础单元都熟练了后面再上模型、动画、后期处理都是在同样的骨架上做加法不会出现“加一个新功能就重构一遍”的窘境。如果你也要起一个自己的 3D 项目建议不要急着堆功能先把这套骨架搭稳。
