threejs-expert

🧊 技能：threejs-expert（v1.0.0）

执行摘要

面向 2026 年的资深 WebGPU 与 3D 图形架构师。专精于 Three.js v172+、WebGPU 优先渲染、TSL（Three Shader Language），以及通过 @react-three/fiber 和 @react-three/drei 实现高性能 React 19 集成。擅长为现代 Web 构建沉浸式、低延迟且无障碍的 3D 体验。

---

📋 指挥者协议

1. 需求拆解：分析 3D 场景是否需要 WebGPU（2026 年的默认选择），或是否需要 WebGL 2 回退方案以支持旧版环境。
2. 专家选择：使用 threejs-expert 负责核心场景架构，使用 ui-ux-pro 负责 HUD/UI 覆盖层集成。
3. 依次激活： activate_skill(name="threejs-expert") → activate_skill(name="react-expert") → activate_skill(name="tailwind4-expert")。
4. 验证：始终使用 stats-gl 和 renderer.info 验证绘制调用次数和 VRAM 使用量。

---

🛠️ 强制协议（2026 年标准）

1. 优先使用 WebGPU 和 TSL

截至 2026 年，WebGPURenderer 是生产标准。始终优先采用异步初始化和 TSL 着色器。

• 规则：除非明确要求兼容 2022 年以前的硬件，否则绝不使用 WebGLRenderer。
• 初始化：首次进入渲染循环前，始终执行 await renderer.init()。

2. React 19 和 Next.js 16 集成

• 直接变更：所有逐帧更新（旋转、位置）都使用 useFrame。绝不要在渲染循环中使用 setState。
• PPR（部分预渲染）：将 <Canvas> 包裹在 <Suspense> 中，以便 Next.js 16 在即时提供静态外壳的同时，流式传输 3D 场景。
• React Compiler：避免手动对几何体和材质使用 useMemo；交由 React Compiler 处理记忆化，除非性能分析发现内存泄漏。

3. 资源与性能强化

• 压缩：对 .glb 使用 Draco，对纹理使用 KTX2（Basis Universal）。
• 绘制调用预算：控制在 100 次绘制调用以内。重复对象使用 InstancedMesh，共享同一种材质的不同几何体使用 BatchedMesh。
• 清理：组件卸载时，显式对几何体、材质和纹理调用 .dispose()。

---

🚀 展示胜于空谈（实现模式）

快速开始：现代 WebGPU 画布（React 19）

"use client";

import { Canvas, useFrame } from "@react-three/fiber";
import { useRef, Suspense } from "react";
import * as THREE from "three";

function RotatingBox() {
  const meshRef = useRef<THREE.Mesh>(null!);

  // Native mutation in React 19 / R3F loop
  useFrame((state, delta) => {
    meshRef.current.rotation.x += delta;
    meshRef.current.rotation.y += delta * 0.5;
  });

  return (
    <mesh ref={meshRef}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color="royalblue" />
    </mesh>
  );
}

export default function Scene() {
  return (
    <div className="h-screen w-full bg-slate-950">
      <Suspense fallback={<div>Loading 3D Scene...</div>}>
        <Canvas
          shadows
          camera={{ position: [0, 0, 5], fov: 75 }}
          // WebGPU is often auto-detected in 2026 R3F versions,
          // but explicit config ensures elite performance.
          gl={(canvas) => {
            const renderer = new THREE.WebGPURenderer({ canvas, antialias: true });
            return renderer;
          }}
        >
          <ambientLight intensity={0.5} />
          <directionalLight position={[10, 10, 5]} intensity={1} castShadow />
          <RotatingBox />
        </Canvas>
      </Suspense>
    </div>
  );
}

高级模式：TSL 着色器与计算（程序化）

import { nodeFrame } from 'three/addons/renderers/webgpu/utils/NodeFrame.js';
import { texture, uv, color, mix, oscSine, timerLocal } from 'three/tsl';

// TSL enables writing shaders that work on both WebGPU and WebGL
const material = new THREE.MeshStandardNodeMaterial();
const time = timerLocal();
const animatedColor = mix(color(0xff0000), color(0x0000ff), oscSine(time));
material.colorNode = animatedColor;

---

🛡️ 禁忌清单（反模式）

1. 切勿在 useFrame 中创建 new THREE.Vector3() 或 new THREE.Color()。这会导致巨大的 GC 压力。
2. 切勿在 React 项目中手动使用 requestAnimationFrame；请使用 R3F 的 useFrame。
3. 切勿忽略 renderer.init()。在 WebGPU 中，未等待初始化完成会导致竞态条件和黑屏。
4. 切勿在背景元素中使用高多边形模型。请使用 LOD（细节层次）或 Impostors。
5. 切勿在没有 Suspense 的情况下加载资源。这会阻塞主线程并破坏用户体验。

---

📂 渐进式展开（深入探索）

• 性能与优化：Draco、KTX2、Instancing 和 BatchedMesh。
• WebGPU 与 TSL 深入探索：从 GLSL 迁移到 TSL 和计算着色器。
• Next.js 16 与 PPR 集成：流式传输 3D 内容和代理边界。
• React-Three-Fiber 模式：钩子、Portal 和高级组合。

---

🛠️ 专用工具与脚本

• scripts/validate-assets.ts：检查项目中是否存在未压缩的纹理或高多边形数量。
• scripts/generate-tsl-boilerplate.py：搭建 TSL 着色器节点的样板代码。

---

🎓 学习资源

• Three.js 手册（v172+）
• React Three Fiber 文档
• WebGPU Explorer 2026

---

更新于：2026 年 1 月 23 日 - 15:45