在正式开始之前我想先说一句Three.js 的基础从来不是背 API而是把场景、相机、渲染器这三个词背后的运行逻辑想明白。很多人照着教程敲了一遍代码看到转动的立方体就觉得自己入门了可一旦自己动手从零写一个简单的三维页面立刻会被各种问题卡住——黑屏、物体看不见、旋转方向不对、动画卡顿……这些问题我全遇到过。所以我今天不打算按官方文档的顺序平铺直叙而是换一种方式从几个最典型的翻车问题出发把 Three.js 的基础知识点串起来讲清楚。这篇文章适合刚刚接触 Three.js、能跑通官方示例但还没完全建立三维思维的人也适合做过一点小项目但始终对某些概念模棱两可的朋友。读完以后你再回头看那些报错和怪现象很多都能一眼定位到原因。1. 先从三个最基础的问题说起1.1 场景、相机、渲染器到底是什么关系很多教程上来就让你写三行代码const scene new THREE.Scene(); const camera new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000); const renderer new THREE.WebGLRenderer();但没人好好解释这三样东西各自是干什么的。我后来用拍电影来类比才彻底想通场景是舞台相机是镜头渲染器是摄影师。舞台上有演员网格物体、灯光光源、背景背景色或天空盒镜头决定你从哪个角度、以什么视野去看舞台摄影师负责把镜头里看到的画面真正拍下来并展示到屏幕上——也就是渲染器执行的 render 方法。这个类比能帮你解决很多问题。比如你在场景里放了一堆物体但相机没有对准它们那就像摄像机架在空地上演员在身后表演你当然什么都看不到。又比如你忘了把渲染器挂到页面上那就相当于摄影师拍了照片但没打印出来屏幕上自然什么都没有。想通这些黑屏问题就解决了一大半。在代码层面场景是一个容器物体、灯光、辅助对象都会被 add 进去。相机是怎么看的配置文件它不会被添加到场景里虽然你也可以 add但通常不需要。渲染器负责创建 canvas 元素、更新画布尺寸、执行绘制。三者缺一不可但它们的职责边界非常清晰。1.2 为什么我看到的永远是黑屏黑屏是 Three.js 新手遇到的第一大问题。我总结下来原因不外乎四种忘记调用renderer.render(scene, camera)或者调用时机不对。相机的位置和观察目标不正确物体在视野之外。物体被添加到了场景但材质是黑色的或者没有加光照。canvas 高度为 0或者渲染器尺寸没有跟随容器。第一种原因最好排查直接在 render 那行打一个断点看有没有执行。第二种原因很常见后面我会专门讲相机。第三种原因和材质、光照有关我会在第三节详细拆。第四种原因则和 CSS 布局有关很多人的页面是 html, body 默认 margin 8pxcanvas 放在 div 里但 div 没有明确高度结果 canvas 高度是 0画面自然空白。我还遇到过一种很隐蔽的情况使用了renderer.setClearColor设置白色背景但场景里放了一个巨型黑色盒子把相机整个包裹住了看起来像黑屏。这种假黑屏就需要你逐个检查场景里的物体范围而不是死盯着渲染器配置。1.3 相机位置和观察目标初次上手最容易搞混透视相机PerspectiveCamera的构造函数有四个参数视野角度 fov、宽高比 aspect、近裁剪面 near、远裁剪面 far。很多教程会给你这样的写法const camera new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000); camera.position.set(0, 0, 5); camera.lookAt(0, 0, 0);为什么默认位置是 (0, 0, 5)因为相机默认在原点如果不往后挪它和物体重叠在一起什么都看不见。Z 轴正方向是朝向屏幕外的所以把相机放在 Z5 的位置就等于让镜头往后拉了 5 个单位才能看到原点附近的物体。这里有个新手特别容易犯的错误只设置了camera.position却没有调用lookAt或者把lookAt写在了物体创建之前。lookAt 的本质是让相机朝向某个点如果相机朝向默认的负 Z 方向而你恰好把物体放在了正 Z 方向那即使物体离相机不远也可能在视野之外。我个人的习惯是每次创建相机后立刻做两件事——先设置 position再设置 lookAt然后把这两行和相机定义写在一起。这样后面无论怎么改相机参数都不会忘记调整朝向。另外fov 越大视野范围越宽物体看起来越小fov 越小长焦效果越明显。调试的时候如果物体突然消失不妨先把 fov 调大看看。2. 坐标系与变换Three.js 的“世界规则”2.1 右手坐标系到底怎么理解Three.js 使用的是右手坐标系X 轴向右Y 轴向上Z 轴朝屏幕外。很多人一听右手就懵其实只需要记住一句话伸出右手拇指朝右是 X食指朝上是 Y中指朝你胸口是 Z。这个坐标系决定了物体旋转的正方向。在左手坐标系里旋转正方向可能和右手坐标系相反。所以你用惯了二维 Canvas 的思维在 Three.js 里做旋转动画时经常会发现顺时针和逆时针和预期相反。这不是 Three.js 的 bug而是坐标系规则决定的。理解坐标系的一个实用场景你想让相机围绕一个物体转圈。如果直接用camera.position.x radius * Math.sin(angle)、camera.position.z radius * Math.cos(angle)你可能需要反复调整角度偏移才能得到想要的运动方向。而一旦你在心里画出一个俯视图知道 XZ 平面是地面Y 是高度这个公式就非常自然了——物体的高度永远在 Y 轴水平位置由 X 和 Z 决定。2.2 物体位置、旋转和缩放到底怎么调才符合直觉每个网格Mesh都有 position、rotation、scale 这三个属性保存的是一个本地坐标系相对父对象坐标系的变换。对一个没有父对象或父对象是场景的物体来说本地坐标系就是世界坐标系。position 最简单就是三维坐标的偏移量。scale 是三维比例默认 (1, 1, 1)。rotation 稍微麻烦一点因为旋转有顺序问题。Three.js 默认使用欧拉角顺序 XYZ也就是说先绕 X 轴旋转再绕 Y 轴最后绕 Z 轴。你可以通过object.rotation.order改成别的顺序比如 YXZ。这个属性特别坑因为如果你同时设置了多个轴的角度最终表现取决于顺序直觉上的目标姿态可能和实际结果对不上。我的建议是在基础阶段尽量别同时绕多个轴旋转同一个物体。如果需要复杂的姿态可以思考一下是不是应该用父子嵌套结构或者使用四元数Quaternion来避免万向锁问题。当然四元数是后面进阶的内容基础阶段知道欧拉角有顺序坑就够了。还有一个隐藏知识点object.position是一个 Vector3 对象。如果你直接写mesh.position.x 1没问题但如果你写const pos mesh.position; pos.x 1;也有效果因为 pos 引用的是同一个 Vector3。这个特性在调试时有用但也容易造成改了半天变量发现还是原来的颜色/位置这类问题——因为有些对象是拷贝有些是引用。2.3 一个五步定位物体的实操案例我模拟一个最常见的场景想在原点正前方偏右的位置放一个立方体然后让相机从斜上方看它。第一步创建立方体网格const geometry new THREE.BoxGeometry(1, 1, 1); const material new THREE.MeshStandardMaterial({ color: 0x00aaff }); const cube new THREE.Mesh(geometry, material);第二步确定物体位置。我希望它在原点前方 3 个单位、右边 2 个单位。在 Three.js 里前方是负 Z 方向所以cube.position.set(2, 0, -3);第三步把它添加到场景scene.add(cube);第四步设置相机。相机从斜上方看位置可以在正后方偏上偏右camera.position.set(4, 3, 5); camera.lookAt(2, 0, -3);第五步渲染并看效果。如果发现立方体偏小就把 camera 的 position 距离拉近一些或者调大 fov。这个流程看起来很普通但很多人会犯一个顺序错误先设置相机 lookAt(0,0,0)再创建物体最后发现物体没在画面中心。lookAt 是指定镜头看哪里的操作它不会因为你后加了物体而自动瞄准它。所以实际项目里最好在每次渲染前都检查一遍相机到底在看什么3. 材质、光照与网格为什么物体“看不见”3.1 材质与光照的依赖关系如果你用 MeshBasicMaterial物体是不受光照影响的它在任何情况下都显示自身的颜色。如果你用 MeshStandardMaterial 或 MeshPhongMaterial物体必须被光源照射到才会显示出来否则就是黑的。这是新手最容易撞上的坑建了立方体用了看起来很高级的标准材质结果屏幕上漆黑一片因为场景里一个光源都没加。为什么会这样因为标准材质要计算光照下的颜色没有光源就无法计算出颜色默认就是黑色。你可以把它理解成一张白纸在白纸本身不发光的情况下你在漆黑的房间里看它它就是黑的。MeshBasicMaterial 相当于一张夜光纸不管有没有灯光都能看到颜色但也没有立体感。所以基础阶段的经验法则是需要真实光影效果就上 MeshStandardMaterial同时一定要至少加一盏 AmbientLight 和一盏 DirectionalLight。想临时验证几何体轮廓可以先用 MeshBasicMaterial省得跟光照问题纠缠。3.2 网格、几何体和材质的三层结构Mesh网格由 Geometry几何体和 Material材质组成。几何体负责定义形状——顶点坐标、法线、UV 等材质负责定义表面属性——颜色、粗糙度、金属度、透明度等。你把两者组合起来才得到一个可以渲染的网格对象。有的新手会疑惑为什么我改了材质颜色但场景里的物体没变化原因通常是你没有把新材质赋给 mesh只是修改了材质对象的颜色属性但那个对象根本没被 mesh 引用。或者你用了 shape 之类的几何体它没有完整的顶点法线需要额外处理。还有一个很重要的概念同一个几何体可以被多个网格共享。比如你想创建 100 个相同形状的立方体只需要一个 BoxGeometry然后创建 100 个 Mesh每个 Mesh 可以有自己的位置、材质。这样可以节省内存因为几何体数据不会重复存储。反过来如果你为每个立方体都 new 一个 BoxGeometry虽然功能没错但内存利用率就很低了。实际操作中我建议把几何体、材质、网格的创建过程分开写方便调试const geometry new THREE.BoxGeometry(1, 1, 1); const material new THREE.MeshStandardMaterial({ color: 0x00aaff }); const mesh new THREE.Mesh(geometry, material);这样出问题时你可以单独检查 geometry 是否正常比如尺寸是否为 0material 是否正常比如颜色是不是纯黑mesh 是否添加到了场景。3.3 没有光照时的应急排查清单当物体“看不见”时按下面顺序检查检查网格是否 add 进了场景scene.children里有没有这个网格。检查材质类型如果是 Standard/Phong 材质场景里必须有光源。检查光源是否生效光源是否 add 进了场景光源的位置是否离物体太远光源的强度是否太低。检查相机是否能看到物体在 render 前临时把相机位置改成 (0, 0, 10)lookAt(0, 0, 0)如果能看到物体说明是相机角度问题。检查物体大小BoxGeometry(1,1,1) 在相机距离 100 的时候几乎是个点需要把相机拉近或者把物体放大。我习惯在初步搭建场景时加一个 AxesHelper 和 GridHelper这样即使物体看不见至少能看到坐标轴和网格能迅速判断相机到底对着哪里。这个习惯帮我省了大量排查时间。4. 动画循环与渲染基础中的核心机制4.1 requestAnimationFrame 和 render 的关系Three.js 的动画不是自动播放的。你用renderer.render(scene, camera)一次页面就静止一帧。要制作动画你需要在每次浏览器刷新屏幕前重新渲染一帧。标准做法是function animate() { requestAnimationFrame(animate); renderer.render(scene, camera); } animate();requestAnimationFrame是浏览器提供的方法它会在下一次绘制之前执行回调。这样animate会反复调用自己形成一个循环。这个循环的节奏通常和显示器刷新率60Hz 或更高保持一致这是它能实现流畅动画的根本原因。新手常见的错误是在 animate 里反复创建几何体或材质。这个操作非常消耗性能而且会让内存持续增长。正确做法是几何体、材质、网格只在初始化阶段创建一次动画循环里只更新 position、rotation 等属性然后重新渲染。还有个细节如果你有多台显示器或者浏览器标签页切换了requestAnimationFrame 会被暂停导致动画停止这其实没什么问题。但如果你的动画依赖真实时间差切回标签页时会发现物体跳了一大段距离——这就是为什么我们后面要用 Clock 来控制时间。4.2 时钟对象与让物体动起来的基础写法让物体转动普通的写法是function animate() { requestAnimationFrame(animate); mesh.rotation.x 0.01; renderer.render(scene, camera); } animate();但这有一个问题rotation 的增量是固定的而帧率可能在不同设备上不同。帧率高的设备物体转得快帧率低的转得慢。为了让动画速度与设备无关应该使用时间差。Three.js 提供了Clockconst clock new THREE.Clock(); function animate() { requestAnimationFrame(animate); const delta clock.getDelta(); mesh.rotation.x 0.5 * delta; // 每秒转 0.5 弧度 renderer.render(scene, camera); } animate();clock.getDelta()返回自上次调用以来经过的时间秒。第一次调用时它会从 Clock 创建时开始计算。注意如果你在动画循环之外调用getDelta()会消耗掉这段时间差导致动画里的 delta 突然变大。正确做法是只在需要时间差的地方调用。用getElapsedTime()可以做往返运动或者按时间变化的动画。比如让物体上下浮动mesh.position.y Math.sin(clock.getElapsedTime() * 2) * 0.5;这样物体的高度会在 -0.5 到 0.5 之间平滑变化频率由倍数决定。用时间驱动动画而不是每帧加固定数值是三维动画基础中最重要的一课。4.3 动画中常见的性能误区很多新手把动画卡顿归咎于 Three.js 性能不行其实大部分情况是代码写得不对。第一个误区在动画循环里new对象。无论是new THREE.Vector3还是new THREE.Mesh都会产生 GC 压力导致不明原因的掉帧。应该尽量复用对象比如用tempVector.copy(某个值)而不是新建。第二个误区在动画循环里调用scene.add和remove太频繁。虽然 Three.js 做了优化但频繁添加删除对象会触发场景遍历和排序最好分批处理。第三个误区忘记更新渲染器尺寸。在窗口缩放时需要重新设置 canvas 尺寸和相机 aspectfunction onResize() { const width window.innerWidth; const height window.innerHeight; renderer.setSize(width, height); camera.aspect width / height; camera.updateProjectionMatrix(); } window.addEventListener(resize, onResize);如果不更新投影矩阵你会发现画面被拉伸或压缩看起来像物体变形。这是一个很基础但特别容易被忽略的地方。第四个误区阴影。阴影是性能大户初学者为了追求效果开了阴影后又给所有物体 castShadow结果卡成 PPT。建议把阴影范围缩小、阴影贴图分辨率调低或者只在关键物体上开启阴影。5. 官方辅助工具与调试基础5.1 轨道控制器让相机操作立刻可用Three.js 有一个非常常用的扩展OrbitControls它能让相机通过鼠标拖拽进行旋转、平移和缩放。这个工具在调试三维场景时几乎是必需品因为没有它你看一个三维物体的唯一办法就是改代码里的相机参数。引入方式因项目而异这里以 ES Module 为例import { OrbitControls } from three/examples/jsm/controls/OrbitControls.js; const controls new OrbitControls(camera, renderer.domElement); controls.enableDamping true; controls.dampingFactor 0.05; controls.target.set(0, 0, 0); controls.update();controls.target就是相机的观察目标点。当你调用camera.lookAt后如果又创建了 OrbitControls它可能会覆盖 camera 视角。所以应该先设置好 camera 和 controls 的 target再调用一次controls.update()。一个常见坑在动画循环里没调用controls.update()导致阻尼效果不生效。如果开启了阻尼必须在每次 render 前调用 update。如果是普通非阻尼模式不调用也能工作但手感会不一样。5.2 辅助对象 AxesHelper 和 GridHelper 的使用时机AxesHelper显示坐标轴红 X、绿 Y、蓝 Z。GridHelper显示地面网格。这两个对象在搭建场景时极其有价值。我通常的做法是const axes new THREE.AxesHelper(5); scene.add(axes); const grid new THREE.GridHelper(10, 10); scene.add(grid);AxesHelper 的 5 表示轴的长度。GridHelper 的参数分别是网格大小和分段数。有了这两个辅助对象你一眼就能看出相机朝向、物体位置的变化。比如物体是不是真的在地面上旋转方向是绕哪个轴对比坐标轴一目了然。不过要记得上线或最终展示前把这些辅助对象去掉。留着会让画面显得很调试但如果你故意想展示坐标系概念那另说。5.3 用 dat.GUI 调整参数的入门姿势dat.GUI现在常被称为 lil-gui是一个轻量级调试面板可以快速调整数字、布尔值、颜色等参数。它对学习 Three.js 帮助极大因为你不需要改代码就能看到参数变化对画面的影响。举个例子import { GUI } from three/examples/jsm/libs/lil-gui.module.min.js; const gui new GUI(); const params { color: 0x00aaff, speed: 0.5, visible: true, }; gui.addColor(params, color).onChange((val) { material.color.set(val); }); gui.add(params, speed, 0, 2, 0.01); gui.add(params, visible).onChange((val) { mesh.visible val; });调颜色、调速度、切换显隐这些在基础学习中都非常直观。我自己初学时的习惯是每学一个特性就加一个 GUI 控件去调它的核心参数比如相机的 fov、物体的旋转速度。这样能把抽象的概念变成可交互的体验理解比光看代码深刻得多。用 GUI 的时候要注意不要在一个页面里创建太多 GUI 实例否则面板重叠不好用。一个 GUI 实例可以添加多个文件夹folder来分组。6. 常见问题速查与避坑笔记6.1 经典报错和现象对照表我整理了一些自己遇到过、也经常在社区看到新人提问的现象写成表格方便对照现象常见原因解决方法整个页面黑屏没有 canvas没有引入渲染器或没有把 canvas 添加到 body检查renderer.domElement是否被 append 到容器canvas 有但场景全黑相机看不到物体或标准材质无光照先加一个 AxesHelper GridHelper再调整相机位置物体显示为黑色剪影材质是 Standard/Phong场景里没有光源或光源强度太弱添加 AmbientLight DirectionalLight调高 light.intensity物体颜色和材质设置不一致修改了材质对象但网格还在用旧材质确认你修改的是 mesh.material 引用的对象旋转动画速度在不同电脑不一样每帧加固定角度没有用时间差使用 Clock 的 getDelta 或 getElapsedTime窗口缩放后画面拉伸没有更新相机 aspect 和渲染器尺寸监听 resize 事件并调用 updateProjectionMatrix鼠标拖拽相机没反应OrbitControls 没有正确实例化或没有传入 renderer.domElement检查new OrbitControls(camera, renderer.domElement)开了阻尼但画面没有平滑效果忘了在动画循环中调用controls.update()在 render 前调用controls.update()物体若隐若现出现闪烁near/far 裁剪面设置不合理或者多个面重叠 z-fighting调整相机 near/far或用 polygonOffset渲染性能突然下降在动画循环里创建对象或加光源把对象创建移到初始化阶段必要时用 InstancedMesh这张表是我实际排查问题的浓缩里面没有花哨的技巧但每一条都对应至少一次真实事故。尤其是裁剪面 near/far很多人设置了 0.1 和 1000 就一直不管但如果场景里有一个特别大的平面相机离得近时后部会被 far 裁剪掉出现物体消失的诡异现象。6.2 我踩过的几个基础坑第一个坑我把renderer创建了两次一次在模块初始化时一次在页面某个事件回调里。结果页面上出现了两个 canvas一个显示内容一个黑屏叠在上面。这个问题很隐蔽因为刷新后以为只是布局问题。排查方法是打开开发者工具看看 body 里有几个 canvas。养成初始化只执行一次的习惯能避免这类问题。第二个坑使用texture时图片还没加载完就把纹理应用到材质上结果物体是黑色的。后来知道需要等图片加载完成或者使用LoadingManager。在基础阶段如果用纹理材质最好先确认图片加载成功再创建 Mesh。第三个坑我为了做地面反射效果给地面材质设了很大的 metalness 和很小的 roughness结果地面变成了一面镜子整个场景里的物体都倒映得乱七八糟。后来才明白金属度高的材质对环境贴图非常敏感在纯色光照场景里容易发黑。基础阶段不建议把材质物理属性调得过猛。第四个坑scale.set(0, 0, 0)会让物体消失。听起来像是废话但有时候你在写代码时不小心把 scale 的某一轴设成 0比如mesh.scale.y 0物体看起来就像一个被压扁的平面。排查物体没了的时候别忘了看一眼 scale。6.3 给新手的练习路径如果让我给一个完全没接触过 Three.js 的人设计练习路径我会推荐按下面这个顺序走只创建一个 Box用 MeshBasicMaterial不加任何光照保证你熟悉 Scene/Camera/Renderer 的最小流程。把材质换成 MeshStandardMaterial添加环境光和方向光理解光照对材质的必要性。手动改相机 position 和 lookAt围绕物体转一圈熟悉三维坐标。用 Clock 让物体缓慢旋转理解时间驱动动画。加入 OrbitControls用鼠标旋转和缩放。加 AxesHelper 和 GridHelper观察物体的相对位置。用 GUI 调参数理解材质颜色、光照强度、旋转速度对画面的影响。尝试创建多个几何体分别放在不同位置练习场景分组Group的概念。到这里你的 Three.js 基础就算真正稳固了。之后再去看阴影、纹理、动画系统、粒子、性能优化等内容就不会觉得一团乱麻。因为你会清楚地知道所有高级功能都是建立在场景—相机—渲染器这个铁三角之上再配合几何体、材质、光源、动画循环这些基础元素。我个人在实际操作中最深的体会是Three.js 的报错其实很少大部分问题表现为画面不符合预期而不是程序崩溃。所以调试三维场景最重要是建立空间感和因果推理能力——当你看到一个异常画面时能快速判断是相机、材质、光照还是动画逻辑的问题。这个能力不是天上掉下来的就是用上面这些辅助工具一点一点攒出来的。你在动手练习时如果遇到卡壳不妨回到这篇里的问题清单逐项排查。等这些问题都变成肌肉记忆你再回头看 Three.js 的基础会发现它们其实非常简单却又是所有复杂三维应用的根基。