用途：在 React Three Fiber 项目中实现自定义 GLSL 或 TSL 材质，包括 uniforms 与顶点变形，主要用于着色器代码编写和调试，而不是用内置材质属性就能表达的效果。
主要能力与用法：先检查已安装的 Fiber、Drei、Three.js 与渲染器版本，示例基于 Fiber 9 / React 19 与 WebGL，需保留项目原有版本。能用内置材质属性表达效果时优先用内置材质；自定义 WebGL 着色可用 Drei 的 shaderMaterial 或原生 <shaderMaterial>。WebGPU 使用 node materials 与 TSL，GLSL ShaderMaterial 和 onBeforeCompile 不可移植到 WebGPU。着色器不会自动获得光照、阴影、雾、实例化或蒙皮，替换内置材质前需先选定所需特性。Drei shaderMaterial 生成 uniform 访问器，可直接赋值 material.uTime；原生 ShaderMaterial 用 material.uniforms.uTime.value。uniform 容器应保持稳定，逐帧只改值、不设 React state，仅改值不要设 material.needsUpdate。着色器源码、defines 与特性变化可能触发重编译，热重载用类的 key，动画中不要改 React key。GLSL 字符串不受 TypeScript 检查，需实际渲染并查看编译器报错。GLSL 写在 JS 模板字符串中，注释里出现反引号或 ${ 会静默截断字符串。
空间、颜色与几何：法线、光照方向与视线方向需处于同一坐标空间；normalMatrix * normal 是视图空间。经 Color 传入的 CSS/十六进制颜色会转为线性工作空间，数值 uniform 向量已是线性，避免二次转换。颜色输入纹理标为 SRGBColorSpace，数据纹理用 NoColorSpace。直接写画布的 WebGL 着色器需按示例做色调映射与输出色彩转换。顶点变形需要足够几何细分；需要光照时同步更新法线；阴影需在深度/距离材质中匹配变形，CPU 射线与包围盒不会自动跟随 GPU 变形。原生自定义实例化着色器需处理 instanceMatrix 与逐实例属性，蒙皮与变形目标同理。
修补内置 WebGL 材质：仅在需要保留内置材质光照时用 onBeforeCompile。着色器 chunk 名称对版本敏感，需查看已安装源码并在 Three.js 更新后渲染测试。回调需在首次编译前设置；配置变化生成不同 GLSL 时提供匹配的 customProgramCacheKey 并触发重编译，动画值放在 uniform 中。不要假设 .clone() 或序列化会保留回调。任务已面向 WebGPU 时优先用 node materials。
限制：资料未提供收费、价格、平台与效果等信息。