1. 前提条件 / 适用场景

前提条件 / 适用场景
- 已有可运行的 React 工程（Vite/Next.js 等皆可）
- 需要一个最小可用的 TSL + R3F 示例
- 浏览器支持 WebGPU 更佳（不支持时可回退 WebGL）

2. 安装

# 安装（读者项目中）
npm i three @react-three/fiber

3. 快速开始（完整示例）

本示例用到 color、 time、 sin、 positionLocal TSL 节点。

import { Canvas, extend } from "@react-three/fiber"
import { WebGPURenderer, MeshBasicNodeMaterial } from "three/webgpu"
import { color, time, sin, positionLocal } from "three/tsl"
import { useMemo } from "react"

// 注册节点材质，使其可在 JSX 中使用 <meshBasicNodeMaterial />
extend({ MeshBasicNodeMaterial })

export default function ColorPlaneTSL() {
  const colorNode = useMemo(() => {
    const R = sin(positionLocal.x.add(time)).add(1).mul(0.5)
    const G = sin(positionLocal.y.add(time)).add(1).mul(0.5)
    const B = sin(positionLocal.x.add(time)).add(1).mul(0.5)
    return color(R, G, B)
  }, [])

  return (
    <Canvas
      gl={async (props) => {
        const r = new WebGPURenderer(props)
        await r.init?.() 
        return r
      }}
      camera={{ position: [0, 0, 2.5], fov: 50 }}
      style={{ width: "100%", height: "100vh", background: "black" }}
    >
      <mesh>
        <planeGeometry />
        <meshBasicNodeMaterial colorNode={colorNode} />
      </mesh>
    </Canvas>
  )
}

3.1 关键片段拆解

（1）注册节点材质

import { extend } from "@react-three/fiber"
import { MeshBasicNodeMaterial } from "three/webgpu"
extend({ MeshBasicNodeMaterial })

（2）创建 WebGPU 渲染器

<Canvas
  gl={async (props) => {
    const r = new WebGPURenderer(props)
    await r.init?.()
    return r
  }}
  camera={{ position:[0,0,2.5], fov:50 }}
/>

（3）构造 TSL 颜色节点

import { color, time, sin, positionLocal } from "three/tsl"
const colorNode = useMemo(() => {
  const R = sin(positionLocal.x.add(time)).add(1).mul(0.5)
  const G = sin(positionLocal.y.add(time)).add(1).mul(0.5)
  const B = sin(positionLocal.x.add(time)).add(1).mul(0.5)
  return color(R, G, B)
}, [])

（4）应用到网格

<mesh>
  <planeGeometry />
  <meshBasicNodeMaterial colorNode={colorNode} />
</mesh>

4. 运行与验证

运行与验证
- 启动开发服务器后，页面显示黑色背景 + 彩色随时间变化的平面
- 控制台无报错

5. 黑屏怎么办

黑屏怎么办
1) 检查浏览器是否支持 WebGPU（Chrome/Edge 开启相应试验性开关或升级）
2) 临时回退 WebGL（示意）：
   import { WebGLRenderer } from "three";
   <Canvas gl={(props) => new WebGLRenderer(props)} ... />
   * 回退后节点/材质支持以 three 所用版本为准

6. 扩展

- 将 MeshBasicNodeMaterial 换为 MeshStandardNodeMaterial 获得光照
- 基于纹理/时间/噪声叠加更多 TSL 节点效果