---

name: threejs-lighting description: Three.js 光照——光源类型、阴影、环境光照。在添加光源、配置阴影、设置 IBL 或优化光照性能时使用。 risk: unknown source: community

Three.js 光照

何时使用

• 你需要在 Three.js 场景中添加或调整光照。
• 任务涉及光源类型、阴影、环境光照或光照性能权衡。
• 你想通过 Three.js 光照设置改善场景可读性、真实感或氛围。

快速开始

import * as THREE from "three";

// Basic lighting setup
const ambientLight = new THREE.AmbientLight(0xffffff, 0.5);
scene.add(ambientLight);

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

光源类型概览

| 光源 | 描述 | 阴影支持 | 开销 | | ---------------- | ---------------------- | -------------- | -------- | | AmbientLight | 均匀照亮所有地方 | 否 | 极低 | | HemisphereLight | 天空/地面渐变 | 否 | 极低 | | DirectionalLight | 平行光线（太阳） | 是 | 低 | | PointLight | 全方向（灯泡） | 是 | 中等 | | SpotLight | 锥形 | 是 | 中等 | | RectAreaLight | 面光源（窗户） | 否* | 高 |

*RectAreaLight 阴影需要自定义解决方案

AmbientLight

均匀照亮所有物体。无方向，无阴影。

// AmbientLight(color, intensity)
const ambient = new THREE.AmbientLight(0xffffff, 0.5);
scene.add(ambient);

// Modify at runtime
ambient.color.set(0xffffcc);
ambient.intensity = 0.3;

HemisphereLight

从天空色到地面色的渐变。适合户外场景。

// HemisphereLight(skyColor, groundColor, intensity)
const hemi = new THREE.HemisphereLight(0x87ceeb, 0x8b4513, 0.6);
hemi.position.set(0, 50, 0);
scene.add(hemi);

// Properties
hemi.color; // Sky color
hemi.groundColor; // Ground color
hemi.intensity;

DirectionalLight

平行光线。模拟远距离光源（太阳）。

// DirectionalLight(color, intensity)
const dirLight = new THREE.DirectionalLight(0xffffff, 1);
dirLight.position.set(5, 10, 5);

// Light points at target (default: 0, 0, 0)
dirLight.target.position.set(0, 0, 0);
scene.add(dirLight.target);

scene.add(dirLight);

DirectionalLight 阴影

dirLight.castShadow = true;

// Shadow map size (higher = sharper, more expensive)
dirLight.shadow.mapSize.width = 2048;
dirLight.shadow.mapSize.height = 2048;

// Shadow camera (orthographic)
dirLight.shadow.camera.near = 0.5;
dirLight.shadow.camera.far = 50;
dirLight.shadow.camera.left = -10;
dirLight.shadow.camera.right = 10;
dirLight.shadow.camera.top = 10;
dirLight.shadow.camera.bottom = -10;

// Shadow softness
dirLight.shadow.radius = 4; // Blur radius (PCFSoftShadowMap only)

// Shadow bias (fixes shadow acne)
dirLight.shadow.bias = -0.0001;
dirLight.shadow.normalBias = 0.02;

// Helper to visualize shadow camera
const helper = new THREE.CameraHelper(dirLight.shadow.camera);
scene.add(helper);

PointLight

从一个点向所有方向发射光线。类似灯泡。

// PointLight(color, intensity, distance, decay)
const pointLight = new THREE.PointLight(0xffffff, 1, 100, 2);
pointLight.position.set(0, 5, 0);
scene.add(pointLight);

// Properties
pointLight.distance; // Maximum range (0 = infinite)
pointLight.decay; // Light falloff (physically correct = 2)

PointLight 阴影

pointLight.castShadow = true;
pointLight.shadow.mapSize.width = 1024;
pointLight.shadow.mapSize.height = 1024;

// Shadow camera (perspective - 6 directions for cube map)
pointLight.shadow.camera.near = 0.5;
pointLight.shadow.camera.far = 50;

pointLight.shadow.bias = -0.005;

SpotLight

锥形光源。类似手电筒或舞台灯。

// SpotLight(color, intensity, distance, angle, penumbra, decay)
const spotLight = new THREE.SpotLight(0xffffff, 1, 100, Math.PI / 6, 0.5, 2);
spotLight.position.set(0, 10, 0);
scene.add(spotLight);

// Properties
spotLight.angle; // Maximum cone angle (radians, max Math.PI/2)
spotLight.penumbra; // Edge softness (0 = hard, 1 = fully soft)
spotLight.distance; // Maximum range
spotLight.decay; // Falloff

环境光照（IBL）

使用 HDR 环境贴图实现基于图像的光照。

import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader";

const rgbeLoader = new RGBELoader();
rgbeLoader.load("environment.hdr", (texture) => {
  texture.mapping = THREE.EquirectangularReflectionMapping;
  scene.environment = texture; // IBL for all PBR materials
  scene.background = texture; // Optional: use as background
});

性能优化

• 限制投射阴影的光源数量（理想情况下 1-2 个）
• 使用较小的阴影贴图尺寸用于不重要的光源
• 对静态场景使用烘焙光照贴图
• 优先使用 DirectionalLight 而非 PointLight（PointLight 需要 6 次渲染通道用于阴影）
• 设置 renderer.shadowMap.autoUpdate = false 用于静态阴影
• 使用 light.shadow.camera 辅助器确保阴影相机紧密包围场景