r3f-postprocessing

React Three Fiber 后期处理

先检查实际使用的渲染器和包的 peer dependencies。此示例针对 WebGL 上的 Fiber 9.7 / React 19、@react-three/postprocessing 3.1 和 postprocessing 6.39。不要随意组合最新版本的包，也不要在项目中悄悄升级。

选择渲染管线

• 此处的 React 后期处理合成器用于 WebGL。Three.js WebGPURenderer 在 r183+ 使用节点效果和 RenderPipeline；请单独验证该后端。
• 让一个主体负责渲染最终场景。EffectComposer 使用正帧优先级；额外的手动 gl.render 可能会覆盖其输出或导致重复渲染。
• 普通 Bloom 可以通过 HDR 阈值隔离明亮表面。只有在确实需要选择对象时才使用 SelectiveBloom；它会增加开销。

实际选中对象的 Bloom

在 Canvas 下方挂载。单击左侧方块可切换选择状态。两个方块都很亮，但只有选中的对象会参与此 Bloom 通道。

import { useMemo, useRef, useState } from 'react'
import { EffectComposer, Select, Selection, SelectiveBloom, ToneMapping } from '@react-three/postprocessing'
import { ToneMappingMode } from 'postprocessing'
import type { DirectionalLight } from 'three'

export default function Example() {
  const light = useRef<DirectionalLight>(null)
  const lights = useMemo(() => [light], [])
  const [selected, setSelected] = useState(true)
  return (
    <Selection>
      <directionalLight ref={light} position={[0, 3, 5]} intensity={2} />
      <Select enabled={selected}>
        <mesh name="bloom-selected" position={[-1.2, 0, 0]} onClick={() => setSelected((value) => !value)}>
          <boxGeometry args={[0.7, 0.7, 0.7]} />
          <meshStandardMaterial color="black" emissive="white" emissiveIntensity={3} />
        </mesh>
      </Select>
      <mesh name="bloom-control" position={[1.2, 0, 0]}>
        <boxGeometry args={[0.7, 0.7, 0.7]} />
        <meshStandardMaterial color="black" emissive="white" emissiveIntensity={3} />
      </mesh>
      <EffectComposer multisampling={0}>
        <SelectiveBloom lights={lights} luminanceThreshold={0} intensity={2} mipmapBlur />
        <ToneMapping mode={ToneMappingMode.ACES_FILMIC} />
      </EffectComposer>
    </Selection>
  )
}

颜色、选择和 refs

• Selection/Select 会向支持选择功能的效果（例如 Outline 和 SelectiveBloom）提供选择信息。将普通 Bloom 包在 Selection 中，并不会让 Bloom 只处理选中的对象。
• 为 SelectiveBloom 提供相关灯光，并确保选择图层与其他图层用途相协调。请测试一个亮度相同但未选中的对象，而不只是测试暗色背景。
• Bloom 在最终色调映射之前处理亮度。请使用自发光/HDR 值和合理的阈值；不要为了强行产生辉光而压平整个场景。
• 此合成器会禁用渲染器的色调映射；请使用 ToneMapping 效果来获得预期的最终外观。让 Bloom/HDR 效果位于色调映射之前，并避免重复进行输出转换。
• ref.current 变为非 null 不会触发 React 重新渲染。不要仅凭 ref 赋值来控制效果的初始挂载；需要以响应式方式使用对象时，请使用受支持的 refs 或回调 ref 状态。

深度和效果特定要求

• 此封装中的 SSAO 需要 <EffectComposer enableNormalPass>；只有效果需要时才启用额外缓冲区。如果文档与实际行为不一致，请检查已安装效果的源码/类型定义。
• DepthOfField 的 target 是世界坐标中的位置（向量/元组），而不是网格 ref。focusDistance={0} 并非通用的自动对焦开关；请使用受支持的 target 或 Autofocus 辅助工具。
• 某些效果属性接受 Three.js Vector2/Vector3 实例，而不是元组。请根据已安装的封装进行类型检查；不要将 JSX 强制转换的假设套用到任意 React 组件上。
• Alpha 混合表面、深度、选择和多重采样会相互影响。请测试实际的透明/透射场景，而不要只依赖不透明方块的截图。

性能和自定义效果

• 从少量效果和适中的 DPR/分辨率开始。谨慎选择抗锯齿策略；不要不加判断地叠加 MSAA、SMAA 和 FXAA。
• 效果数量不等于渲染通道数量：兼容的效果可以合并。卷积/深度效果和辅助缓冲区仍可能开销很大；请测量 GPU 开销。
• 优先使用受支持的封装组件。对于自定义后期处理 Effect，请遵循 mainImage/mainUv、uniforms、输入缓冲区和效果属性契约；改变 UV 的效果需要相应的卷积声明。
• 明确管理自定义 Effect 实例的清理责任。没有负责人时不要使用 dispose={null}，也不要从一个使用者处置共享效果。
• 更新后请检查动态属性是否受支持：仅在构造时生效的设置可能会重新创建效果。不要每帧重建合成器来为 uniform 设置动画。

验证

渲染完整管线，切换效果/选择状态，调整大小，并在 Strict Mode 下卸载/重新挂载。确认仅选中对象生效且最终颜色输出正确；TypeScript 无法证明这两点。

来源

• Selection、SelectiveBloom、Bloom。
• 已发布的封装源码 — 合成器、SSAO、引用和目标类型。
• Postprocessing、Three.js 迁移指南。