three.js 入门：10 分钟让网页转起第一个 3D 立方体的上手指南

【免费下载链接】three.js JavaScript 3D Library. 项目地址: https://gitcode.com/GitHub_Trending/th/three.js

three.js 是一个跨浏览器的 JavaScript 3D 库，底层基于 WebGL 与 WebGPU，把着色器、矩阵这些渲染细节封装成高层对象。你不需要手写 GLSL，只需搭建 scene（场景容器）、camera（观察视角）、renderer（画面输出器）三个对象，就能在网页里看到实时 3D 画面。本文会先帮你判断项目是否适合所用场景，再带你完成一次最小渲染验证，最后给出从示例升级到可用页面的路径与一份排错清单。

先判断：three.js 是否适合你的页面场景

选库前先把用途对照一下，能省掉大量返工：

你的场景	是否适合	判断理由
轻量网页 3D、互动小特效	适合	十几行代码即可出画面，产物体积小
产品 3D 展示、商品旋转预览	适合	官方扩展里有现成的相机控制与模型加载模块
数据可视化、图表 3D 化	适合	几何体、材质 API 足够支撑点线面级别的可视化
复杂实时 3D 产品（大型场景、高帧率）	需谨慎	需要自己优化绘制调用、显存与后处理开销
重度游戏、引擎级项目	不建议	缺物理、碰撞等系统，更适合 Unity、Unreal 这类引擎

一句话原则：页面级 3D 内容放心用；接近引擎复杂度的需求，先做性能压测再决定。

最小验证：从仓库到看到 3D 画面

最短路径共 5 步，每步都只验证一件事：

1. 获取仓库：克隆时加 --depth=1 只取最新提交，比全量历史小得多。

   git clone --depth=1 https://gitcode.com/GitHub_Trending/th/three.js
   cd three.js
   npm install
   

2. 准备 HTML 入口：three.js 采用 ES Module 加载，在 <head> 里放一段 type="importmap" 的脚本，把 three 指向 src/Three.js，把 three/addons/ 指向 examples/jsm/。importmap 声明必须先于模块脚本出现，顺序反了就会报模块解析错误。

3. 写渲染脚本：创建场景、透视相机、一个带法线材质的立方体，把渲染器的 domElement 挂进页面，再用 setAnimationLoop 注册每帧回调并驱动旋转。

4. 起本地服务器：用 python3 -m http.server 8080 启动静态服务，别用 file:// 协议直接双击 HTML。

5. 看验证标准：浏览器里出现一个随时间旋转的彩色立方体，控制台无报错，即说明 WebGL 渲染链路已通。

核心脚本长这样，只需这几行 API：

import * as THREE from 'three';

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(70, innerWidth / innerHeight, 0.1, 100);
camera.position.z = 2;
scene.add(new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshNormalMaterial()));

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement);
renderer.setAnimationLoop((t) => {
  scene.children[0].rotation.set(t / 2000, t / 1000, 0);
  renderer.render(scene, camera);
});

从示例到可用页面

最小 demo 跑通后，按下面四个方向逐步加功能即可，每一步都对应仓库里现成的模块与示例。

添加相机控制，让页面可交互

给页面挂上 OrbitControls，鼠标拖拽旋转、滚轮缩放就能实现，做模型预览或数据展示时最常用。从 three/addons/controls/OrbitControls.js 引入，构造时传入相机和渲染器的 domElement。注意开启 enableDamping 后，必须在每一帧渲染前手动调用 controls.update()，惯性效果才会生效。

加载 glTF 模型，把资产放进网页

仓库内 examples/models/gltf/ 目录存放了可直接使用的测试模型，练手不用另外找素材。用 GLTFLoader 加载，成功回调里把 gltf.scene 加进场景即可。建议加载完成后按模型的包围盒重新设置相机距离，避免模型出屏或太小。

加入后处理效果，提升画面表现

泛光、模糊、色彩分级等效果集中在 examples/jsm/postprocessing/，先创建 EffectComposer 并挂上基础渲染通道，再把 UnrealBloomPass 等通道按顺序 addPass。添加后要把每帧输出对象从场景换成 composer。注意每多一条后处理通道就多一次全屏渲染，低性能设备上应酌情裁剪。

处理粒子、性能与显存问题

大批量粒子优先走 GPU 方案：WebGPU + TSL 节点着色语言可在计算通道里直接更新粒子状态，参考 examples/ 下的 webgpu_compute_particles 系列页面。WebGL 路线可评估 examples/jsm/gpgpu/ 或实例化渲染（instancing）。无论哪条路线，动态创建又销毁的对象都要在移除前调用 geometry 与 material 的 dispose() 释放显存。

排错与性能检查清单

按出现频率从高到低排列，逐项自查：

1. 显存持续上涨、场景越跑越卡 常见原因：动态对象只移除了节点引用，没调 dispose()，GPU 端纹理与缓冲区只增不减。 处理动作：在对象移除流程里补 geometry.dispose() 和 material.dispose()，纹理资源同样释放。
2. glTF 模型加载失败、回调不触发 常见原因：路径写错，或模型引用的贴图、二进制文件与 .gltf 不在约定目录关系里。 处理动作：打开 Network 面板确认每个子资源都是 200，并对照 examples/models/gltf/ 的目录结构自查相对路径。
3. importmap 未生效，报 "Failed to resolve module specifier" 常见原因：importmap 脚本写在模块脚本之后，声明来不及生效。 处理动作：检查 <head> 内两段脚本的先后顺序，确保 importmap 在前。
4. 双击打开 HTML 后资源全部加载失败 常见原因：file:// 协议下浏览器 CORS 策略拦截了 fetch 请求。 处理动作：改用任意静态服务器（如 python3 -m http.server）通过 http 访问。
5. 场景结构混乱，排查全靠 console.log 常见原因：对象层级复杂，缺少可视化工具。 处理动作：在 chrome://extensions 开启开发者模式，加载 devtools/ 目录下的仓库自带调试扩展，DevTools 中的 Three.js 标签页可以树状查看场景对象与几何体类型，定位问题明显更快。

three.js 适合页面级 3D：产品展示、数据可视化、轻量互动，都可以直接采用。如果你的项目走向大型实时 3D，需要自己处理绘制批次、显存与后处理开销，或者需要完整引擎能力，就该提前做性能压测、考虑更重的方案。建议现在就按"最小验证"一节把立方体转起来，再依次叠加相机控制和 glTF 模型，每步都在浏览器里确认结果。

【免费下载链接】three.js JavaScript 3D Library. 项目地址: https://gitcode.com/GitHub_Trending/th/three.js