r3f-materials

React Three Fiber 材质

先检查已安装的渲染器、Three.js、Fiber 和 Drei 版本。示例使用 Fiber 9 / React 19 和 WebGL。不要假设基于着色器的 Drei 材质在 WebGPU 中也能正常工作。

选择满足需求的最简单材质

需求	起点	限制
无光照艺术效果或 UI 表面	meshBasicMaterial	仍受输出颜色／色调映射策略影响
普通 PBR 表面	meshStandardMaterial	金属尤其需要环境光或合适的灯光
清漆层、透射、光泽	meshPhysicalMaterial	只启用需要的功能；着色器计算更多
风格化照明	meshToonMaterial	需要灯光；渐变贴图需要适当的过滤方式
法线调试	meshNormalMaterial	适用于检查几何体／法线
自定义着色	ShaderMaterial 或节点材质	匹配 WebGL/GLSL 与 WebGPU/TSL

使用环境光照的 PBR 表面

放在 Canvas 下方。这个小型程序化环境无需依赖远程预设。

import { Environment, Lightformer } from '@react-three/drei'

export default function Example() {
  return (
    <>
      <Environment resolution={64} frames={1}>
        <Lightformer position={[0, 3, 2]} scale={[5, 5, 1]} intensity={3} />
      </Environment>
      <mesh>
        <sphereGeometry args={[1, 32, 24]} />
        <meshStandardMaterial color="goldenrod" metalness={1} roughness={0.3} />
      </mesh>
    </>
  )
}

PBR 与颜色设置

• 电介质的金属度接近 0，裸金属的金属度接近 1；中间值通常表示混合材质或纹理过滤效果。粗糙度控制微表面响应，而非不透明度。
• 颜色／反照率和自发光贴图使用 sRGB；粗糙度、金属度、法线、AO 和遮罩使用 NoColorSpace。保留正确加载的 glTF 纹理元数据。
• 贴图会与标量设置相乘：metalness={0} 时金属度贴图不起作用；自发光贴图需要非黑色的自发光颜色。
• 法线贴图会改变着色；置换贴图会改变顶点，因此需要足够的几何细分。法线贴图不会改变轮廓。
• 自发光表面不会照亮附近的几何体，也不会自动产生光晕。如需这些效果，请添加适当的灯光和泛光管线。
• 最近几个 Three.js 版本的 PBR 外观有所变化。请在受控的灯光／曝光条件下验证；升级后不要盲目通过增加灯光或颜色转换来补偿。

透明度与玻璃

• 对普通 Alpha 混合而言，opacity < 1 时需要设置 transparent。对于镂空树叶或贴花，可考虑使用 alphaTest 来避免排序瑕疵；只有在确有需要时才选择柔和透明效果。
• depthWrite={false} 有助于处理某些透明图层，但并非通用修复方案。请测试重叠顺序、背面以及与不透明物体的交叉情况。
• 玻璃使用物理透射，通常保持 opacity 为 1，并设置有意义的 thickness/IOR。透射不等同于普通透明度。
• Drei 的 MeshTransmissionMaterial 和 MeshReflectorMaterial 会额外渲染场景。请从较低的分辨率／采样数开始，并在启用背面渲染或为每个对象分配独立缓冲区之前进行测量。
• 在某些场景中，共享透射采样器成本更低，但无法还原透明／透射物体之间的所有可见性关系。选择前请阅读该辅助工具的文档。
• 不要到处启用 DoubleSide：这会增加渲染成本，还可能掩盖错误的绕序或法线。

生命周期与更新

• 需要共享外观的对象应共用材质。修改某个实例的颜色、贴图或 uniforms 前请先克隆；缓存的 glTF 材质可能还在其他地方使用。
• R3F 管理声明式材质子项的生命周期。外部分配或共享的材质需要明确管理生命周期。释放材质不会释放其纹理。
• 通过类型化 ref 为普通材质属性添加动画。粗糙度或颜色等值的变化不需要 needsUpdate；添加／移除贴图等着色器功能变化则可能需要重新编译。
• 材质数组需要与几何体组相匹配。仅提供数组不会将任意材质分配给各个面。

验证

在目标灯光和输出管线下渲染，然后测试透明物体的重叠、阴影以及反复挂载／卸载。添加透射或反射渲染通道前，请先比较 GPU 成本。

Sources

• MeshStandardMaterial, MeshPhysicalMaterial, Material.
• Drei transmission material, reflector material.
• Color management, Three.js migration guide.