r3f-lighting

React Three Fiber 灯光

首先检查已安装的 Three.js、Fiber 和 Drei 版本，以及渲染器。本示例面向 Fiber 9 / React 19、Three.js r185 和 WebGL。

从经过规划的灯光设置开始

• 使用环境光照提供 PBR 反射和补光，使用直接光提供方向性照明和实时阴影。增加环境光无法补回缺失的金属反射。
• 场景背景和 scene.environment 用途不同。Drei Environment 用于设置光照；background 还会让环境显示在场景后方。
• 在生产环境中，优先使用自有 HDR/EXR 资源。Drei 预设适合原型开发，但依赖外部托管。选择较新的格式前，请先确认加载器支持情况。
• Sky 是可见的天空几何体，不会自动匹配太阳光或环境光照。需要保持视觉一致时，应让天空、直接光和环境光照相互协调。

带阴影的场景

在 <Canvas shadows="percentage"> 内挂载。在 Three.js r182+ 中，PCFShadowMap 是软阴影；Fiber 9 中不带参数的 shadows 会选择已弃用的 PCFSoftShadowMap。

export default function Example() {
  return (
    <>
      <ambientLight intensity={0.3} />
      <directionalLight
        position={[3, 5, 3]}
        intensity={3}
        castShadow
        shadow-mapSize={[1024, 1024]}
        shadow-camera-left={-4}
        shadow-camera-right={4}
        shadow-camera-top={4}
        shadow-camera-bottom={-4}
        shadow-camera-near={0.5}
        shadow-camera-far={15}
        shadow-normalBias={0.02}
      />
      <mesh castShadow position={[0, 0.5, 0]}>
        <boxGeometry />
        <meshStandardMaterial color="coral" />
      </mesh>
      <mesh receiveShadow rotation={[-Math.PI / 2, 0, 0]}>
        <planeGeometry args={[8, 8]} />
        <meshStandardMaterial color="silver" />
      </mesh>
    </>
  )
}

上面的偏差和视锥值适用于这个小场景；实际使用时请根据尺寸重新调整。

阴影与光照目标

• 阴影贴图需要启用渲染器阴影、设置投射阴影的光源、可投射阴影的网格，以及可接收阴影的材质/网格。环境光和半球光不会投射阴影。
• 提高贴图分辨率前，先将阴影相机视锥缩小到有用区域。使用 CameraHelper 检查其视锥；偏差应能解决阴影痤疮问题，同时避免阴影与物体脱离。
• 点光源阴影会渲染六个方向。应限制投射阴影的光源数量和大型贴图；开销取决于受影响的几何体和渲染通道，而不只是光源数量。
• 移动方向光/聚光灯的目标时，需要使用世界矩阵会更新的目标 Object3D。将自定义目标添加到场景图中；只更改一个已脱离场景图的目标位置，可能会导致其世界变换过期。
• 在 WebGL 中，RectAreaLight 会影响 Standard/Physical 材质，但不会投射内置阴影。使用需要 RectAreaLightUniformsLib 的原生光源路径时，请进行初始化。
• 在 WebGLRenderer 中，对象/相机图层并不是通用的逐光源材质遮罩。不要承诺让光源图层与网格图层匹配就能实现选择性照明。

环境与辅助工具开销

• Drei Lightformer 是被 Environment 捕获的自发光几何体；它不是普通的实时光源，也不会投射直接光阴影。
• 对真正静态的环境捕获或 ContactShadows，设置 frames={1}。动画物体/灯光需要重新捕获；冻结的捕获内容会一直过期。
• ContactShadows 会渲染离屏深度/模糊近似效果。它并非没有开销，也无法取代所有方向光阴影。
• AccumulativeShadows 会随采样逐渐收敛；场景发生变化时，可能需要重置/重新累积。BakeShadows 会冻结更新，而不是生成可移植的烘焙光照贴图。
• SoftShadows 会修改 WebGL 着色器代码。添加前请先确认它与已安装的 Three.js 阴影实现兼容，尤其是在升级渲染器后。
• 调整灯光时，保持色调映射/曝光一致。当前基于物理的光照强度不应与旧版传统光照教程中的设置盲目混用。

验证

检查阴影接触效果、痤疮、裁剪情况、已加载模型的投射/接收阴影标记，以及移动物体。比较静态与动画捕获行为，并在目标设备上测量总渲染通道数。

来源

• Drei 环境光照、ContactShadows。
• Three.js 阴影、RectAreaLight、DirectionalLight。
• 迁移指南 — r182 中的 PCF 变更，以及 r184 中的环境旋转变更。