在 React Three Fiber 中配置纹理颜色空间…

适用于 React Three Fiber/Three.js/Drei 项目中需要正确处理颜色贴图与数据贴图、UV 通道、采样、视频纹理、渲染目标和纹理缓存/释放的场景。

适用场景

解决思路

1. 先检查已安装的 Three.js、Fiber、Drei 和 renderer 版本；示例对应 Fiber 9 / React 19、Three.js r185 和 WebGL。
2. 优先保留已经正确配置的资产，不要为了统一而重置每一张纹理。
3. 按纹理内容标注颜色空间：PNG/JPEG 基础色或自发光色用 SRGBColorSpace；roughness、metalness、normal、AO、alpha/masks 用 NoColorSpace；线性 HDR/EXR 光照数据保留 loader 提供的线性元数据。
4. 区分 NoColorSpace 与 LinearSRGBColorSpace：标量/向量数据没有颜色空间；不要把所有 map 一律转成 sRGB。
5. 加载颜色贴图时，在 Canvas 内的 Suspense 下挂载使用纹理的组件；文件路径是应用资产，不是本技能提供的文件。
6. 使用 useTexture('/textures/checker.png', (texture) => { texture.colorSpace = SRGBColorSpace; texture.needsUpdate = true }) 加载颜色贴图，并把它传给 meshStandardMaterial 的 map，例如配合 <planeGeometry args={[3, 3]} />、<meshStandardMaterial map={map} roughness={1} />。
7. Fiber 会处理常见的内置颜色贴图 props，glTF loader 也会设置纹理元数据；但对自定义 shader uniform 或手动创建的纹理，显式标注尤其重要。
8. 了解 useTexture/useLoader 按 loader 和 URL 输入缓存：同一来源可能返回同一个 Texture 对象；修改 repeat、offset、wrapping、filters、colorSpace 会影响所有消费者。
9. 在按实例配置前克隆 Texture 对象；尽可能复用底层 image；只 dispose 自己拥有的克隆，不要从单个消费者 dispose 缓存源。
10. 不要在渲染期间清空 loader cache；缓存驱逐和 GPU 释放是不同操作，必须确认没有活动消费者仍需要该资源。
11. 不要每帧替换 uniform/texture 对象；直接更新 offset 或自己拥有的值；在按需渲染循环中，命令式修改后调用 invalidate。
12. 设置 texture.channel = 0 选择 uv，1 选择 uv1，再选择 uv2、uv3；选择几何体实际存在的属性；AO/light map 不再一律要求把 uv 复制到 uv2。
13. 让重复超出 [0, 1] 时使用 RepeatWrapping 或 MirroredRepeatWrapping；offset/repeat/rotation 是纹理变换；atlas 动画通常不需要每帧 React state。
14. Wrapping、颜色空间、上传配置变更可能需要 texture.needsUpdate；offset/repeat 变更使用 texture matrix，通常不需要重新上传图像数据。
15. 像素画有意使用 nearest filtering；缩小表面用 mipmaps 减少闪烁；anisotropy 上限取 renderer 支持的最大值和场景需要。
16. 不要只按 2 的幂尺寸要求处理 WebGL2；根据屏幕覆盖、内存、压缩格式约束和质量来决定纹理尺寸，而不是过时的一刀切规则。
17. 区分下载大小与 GPU 内存大小；在支持时考虑 KTX2/Basis；有意识地配置 renderer 能力检测并托管 decoder/transcoder 资产。
18. 替换 glTF 颜色贴图时，匹配模型的 UV/朝向约定；手动加载的纹理通常需要 flipY=false；不要再次翻转已经配置好的 glTF 贴图。
19. 当 useVideoTexture 的生命周期适合时优先使用；检查 autoplay/muting、CORS、用户手势、源清理；改变视频分辨率可能需要新纹理；不要承诺所有浏览器 autoplay 都会成功。
20. Canvas/DataTexture 内容变化需要 needsUpdate；数据纹理应保持数据颜色空间语义；不要在帧循环里创建纹理，除非有意管理资源和泄漏。
21. 对 render target，阅读 offscreen rendering（references/render-targets.md）；绝不要在渲染到同一 target 时从该 target 的纹理采样。
22. 环境贴图保持在光照路径上（Environment/useEnvironment），不要把普通 2D 图像在没有合适 mapping/PMREM 流程时直接赋值上去。
23. 测试已知颜色色块、变化光照下的数据贴图、纹理朝向、重复挂载、两个使用不同 UV 变换的消费者；检查 GPU texture counts；counts 不是字节级精确内存测量。

适用边界 · 注意事项

• 任务核心是模型加载流程时，应查 loader 指南，而不是用本经验替代。
• 纹理已由 glTF loader 或框架正确配置且无需覆盖时，不要重置；不要把所有贴图一律转成 sRGB。
• 不了解缓存和活动消费者时，不要清空 loader cache，也不要释放或覆盖共享纹理资源。