Three.js 零基础入门——从环境搭建到第一个3D场景

摘要

本文是一篇面向初学者的 Three.js 入门指南。文章首先介绍了 Three.js 作为基于 WebGL 的 JavaScript 3D 库的核心优势，并详细解析了构建 3D 场景的三大基石：场景（Scene）、相机（Camera）和渲染器（Renderer）。随后，文章提供了 CDN 与 npm+Vite 两种环境搭建方式，并附带了一套完整的实战代码，演示了从创建场景、配置相机与渲染器，到添加几何体、灯光及实现动画循环和窗口自适应的全流程。最后，文章总结了物体不显示、模型全黑及裁切面设置不当等常见开发问题与避坑建议，帮助开发者快速上手。

[一、什么是 Three.js](#一、什么是 Three.js)

二、核心概念：场景、相机、渲染器

三、环境搭建

[方式一：CDN 引入](#方式一：CDN 引入)

[方式二：npm + Vite（推荐）](#方式二：npm + Vite（推荐）)

四、完整示例代码

五、常见问题与避坑指南

一、什么是 Three.js

Three.js 是一个基于 WebGL 的 JavaScript 3D 库，它封装了复杂的底层图形操作，提供了简洁的 API 接口，让开发者无需掌握 WebGL 的底层细节就能快速搭建交互式的 3D 场景。无论是游戏开发、3D 数据可视化、交互式产品展示，还是艺术创作，Three.js 都能满足你的需求。

二、核心概念：场景、相机、渲染器

任何 Three.js 程序都依赖三个核心组件，这是搭建 3D 场景的基石：

场景（Scene） ：3D 世界的容器，所有物体、灯光、相机都要添加到场景中
相机（Camera） ：模拟人眼视角，决定哪些内容会被渲染到屏幕上
渲染器（Renderer） ：负责将 3D 场景绘制到 2D 屏幕上

三、环境搭建

方式一：CDN 引入

html

复制代码

<script type="importmap">
{
    "imports": {
        "three": "https://unpkg.com/three@0.160.0/build/three.module.js"
    }
}
</script>

方式二：npm + Vite（推荐）

bash

复制代码

npm create vite@latest my-three-app -- --template vanilla
cd my-three-app
npm install three
npm run dev

四、完整示例代码

javascript

复制代码

import * as THREE from 'three';

// 1. 创建场景
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x87CEEB); // 设置背景色为天蓝色[reference:5]

// 2. 创建透视相机
// 参数：视场角75°，宽高比自适应，近裁切面0.1，远裁切面1000[reference:6]
const camera = new THREE.PerspectiveCamera(
    75,
    window.innerWidth / window.innerHeight,
    0.1,
    1000
);
camera.position.z = 5;

// 3. 创建渲染器
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// 4. 创建立方体
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshStandardMaterial({
    color: 0x00ff00,
    roughness: 0.5,
    metalness: 0.8
});
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

// 5. 添加灯光
const ambientLight = new THREE.AmbientLight(0x404040);
scene.add(ambientLight);

const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8);
directionalLight.position.set(1, 1, 1);
scene.add(directionalLight);

// 6. 动画循环[reference:7]
function animate() {
    requestAnimationFrame(animate);
    cube.rotation.x += 0.01;
    cube.rotation.y += 0.01;
    renderer.render(scene, camera);
}
animate();

// 7. 窗口自适应
window.addEventListener('resize', () => {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();
    renderer.setSize(window.innerWidth, window.innerHeight);
});

五、常见问题与避坑指南

物体不显示 ：检查相机位置是否在物体前方，默认相机在原点 (0,0,0)，需要调用 camera.position.z = 5 拉开距离
模型全黑：忘记添加灯光，至少需要一个环境光 AmbientLight
近/远裁切面设置不当：near 太小或 far 太大会影响性能，near 设 0.1、far 设 1000 适合大多数场景