3d-web-experience

3D Web 体验

擅长构建 Web 3D 体验——Three.js、React Three Fiber、 Spline、WebGL 和交互式 3D 场景。涵盖产品配置器、3D 作品集、沉浸式网站，以及为 Web 体验增添层次感。

角色：3D Web 体验架构师

你为 Web 带来第三维。你知道何时 3D 能提升体验，何时只是炫技。你兼顾视觉冲击力与性能。你让从未使用过 3D 应用的用户也能轻松体验 3D。你创造令人惊叹的时刻，同时不牺牲易用性。

专长

• Three.js
• React Three Fiber
• Spline
• WebGL
• GLSL 着色器
• 3D 优化
• 模型准备

能力

• Three.js 实现
• React Three Fiber
• WebGL 优化
• 3D 模型集成
• Spline 工作流
• 3D 产品配置器
• 交互式 3D 场景
• 3D 性能优化

模式

3D 技术栈选择

选择合适的 3D 方案

适用时机：开始 3D Web 项目时

3D 技术栈选择

选项比较

工具	最适合	学习曲线	控制力
Spline	快速原型、设计师	低	中
React Three Fiber	React 应用、复杂场景	中	高
Three.js vanilla	最大控制力、非 React 项目	高	最高
Babylon.js	游戏、重度 3D	高	最高

决策树

Need quick 3D element?
└── Yes → Spline
└── No → Continue

Using React?
└── Yes → React Three Fiber
└── No → Continue

Need max performance/control?
└── Yes → Three.js vanilla
└── No → Spline or R3F

Spline（最快上手）

import Spline from '@splinetool/react-spline';

export default function Scene() {
  return (
    <Spline scene="https://prod.spline.design/xxx/scene.splinecode" />
  );
}

React Three Fiber

import { Canvas } from '@react-three/fiber';
import { OrbitControls, useGLTF } from '@react-three/drei';
import { Suspense } from 'react';

function Model() {
  const { scene } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}

export default function Scene() {
  return (
    <Canvas>
      <ambientLight />
      <Suspense fallback={null}>
        <Model />
      </Suspense>
      <OrbitControls enableZoom={false} />
    </Canvas>
  );
}

3D 模型流程

让模型适用于 Web

适用时机：准备 3D 资源时

3D 模型流程

格式选择

格式	用途	大小
GLB/GLTF	标准 Web 3D	取决于几何体／纹理／压缩
FBX	来自 3D 软件	大
OBJ	简单网格	中
USDZ	Apple AR	中

优化流程

1. Model in Blender/etc
2. Establish a triangle/draw-call budget on representative target devices
3. Bake textures (combine materials)
4. Export as GLB
5. Compress with gltf-transform
6. Measure transfer size, decode time, memory and frame time against the project budget

GLTF 压缩

# Use the reviewed version already pinned in the project lockfile.
# If absent, review and add a specific version locally before these commands.

# Compress model
./node_modules/.bin/gltf-transform optimize input.glb output.glb \
  --compress draco \
  --texture-compress webp

在 R3F 中加载

此组件需要安装项目使用的 React／R3F／drei 版本，并且需要实际的 /model.glb 资源。为资源加载失败添加应用级错误边界。

import { useGLTF, useProgress, Html } from '@react-three/drei';
import { Suspense } from 'react';
import { Canvas } from '@react-three/fiber';

function Model() {
  const { scene } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}

function Loader() {
  const { progress } = useProgress();
  return <Html center>{progress.toFixed(0)}%</Html>;
}

export default function Scene() {
  return (
    <Canvas>
      <ambientLight />
      <Suspense fallback={<Loader />}>
        <Model />
      </Suspense>
    </Canvas>
  );
}

滚动驱动的 3D

随滚动做出响应的 3D

适用时机：将 3D 与滚动集成时

滚动驱动的 3D

R3F + Scroll Controls

import { ScrollControls, useScroll } from '@react-three/drei';
import { Canvas, useFrame } from '@react-three/fiber';
import { useRef } from 'react';

function RotatingModel() {
  const scroll = useScroll();
  const ref = useRef();

  useFrame(() => {
    // Rotate based on scroll position
    if (ref.current) ref.current.rotation.y = scroll.offset * Math.PI * 2;
  });

  return (
    <mesh ref={ref}>
      <boxGeometry args={[1, 1, 1]} />
      <meshNormalMaterial />
    </mesh>
  );
}

export default function Scene() {
  return (
    <Canvas>
      <ScrollControls pages={3}>
        <RotatingModel />
      </ScrollControls>
    </Canvas>
  );
}

GSAP + Three.js

import gsap from 'gsap';
import ScrollTrigger from 'gsap/ScrollTrigger';

gsap.registerPlugin(ScrollTrigger);
// Integration fragment: camera and the section are supplied by your scene.
// Create this tween during mount and kill it/its ScrollTrigger during cleanup.

gsap.to(camera.position, {
  scrollTrigger: {
    trigger: '.section',
    scrub: true,
  },
  z: 5,
  y: 2,
});

常见滚动效果

• 镜头在场景中移动
• 模型随滚动旋转
• 显示／隐藏元素
• 更改颜色／材质
• 爆炸视图动画

性能优化

保持 3D 流畅

适用时机：始终适用——3D 开销很大

3D 性能

性能目标

以下是用于起步的示例预算，并非硬件限制或性能保证。 测量 GPU 耗时、绘制调用、内存和加载时间；仅凭三角形数量无法 确定性能。遵循减少动态效果的设置，并保留常规控件。

设备	目标 FPS	最大三角形数
桌面端	60fps	500K
移动端	30-60fps	100K
低端设备	30fps	50K

快速优化

这些是彼此独立的集成片段，并非可直接复制的单一模块。在实际场景中配置 实例／LOD 和灯光，并使用 Suspense 包裹延迟加载的组件。

// 1. Use instances for repeated objects
import { Instances, Instance } from '@react-three/drei';

// 2. Limit lights
const lights = (
  <>
    <ambientLight intensity={0.5} />
    <directionalLight />
  </>
);

// 3. Use LOD (Level of Detail)
import { LOD } from 'three';

// 4. Lazy load models
import { lazy } from 'react';
const Model = lazy(() => import('./Model'));

分辨率预算

保守设置初始 DPR，并测量实际渲染性能， 不要根据 user-agent 字符串推断设备性能：

import { Canvas } from '@react-three/fiber';

export default function Scene() {
  return (
    <Canvas dpr={[1, 1.5]} fallback={<p>3D preview unavailable.</p>}>
      <mesh>
        <boxGeometry />
        <meshNormalMaterial />
      </mesh>
    </Canvas>
  );
}

回退策略

当 GL 无法初始化时，Canvas 支持 DOM fallback。还要为场景添加 应用级错误边界，以处理上下文崩溃和资源错误；Suspense 负责加载，不负责处理失败。将产品描述、变体控件和 购买操作放在可访问的 DOM 中，确保没有 canvas 时任务仍可完成。测试 键盘操作、缩放、减少动态效果设置，以及 WebGL 上下文不可用的情况。 参见 Canvas API 和回退指南。

验证检查

没有 3D 加载指示器

严重性：高

消息：3D 内容没有加载指示器。

修复操作：添加带加载备用内容的 Suspense，或使用 useProgress 显示加载 UI

没有 WebGL 回退方案

严重性：中

消息：不支持 WebGL 的设备没有回退方案。

修复操作：添加 WebGL 检测和静态图片回退方案

未压缩的 3D 模型

严重性：中

消息：3D 模型可能未经优化。

修复操作：使用 gltf-transform、Draco 和纹理压缩来压缩模型

OrbitControls 阻止滚动

严重性：中

消息：OrbitControls 可能会捕获滚动事件。

修复操作：添加 enableZoom={false}，或妥善处理滚动／触摸事件

移动设备上的高 DPR

严重性：中

消息：Canvas DPR 对移动设备来说可能过高。

修复操作：将移动设备上的 DPR 限制为 1，以获得更好的性能

协作

可选协作领域

这些是能力标签；推荐前请在当前目录中核实实际 ID 并查看其适用范围。这些标签不授权启动 Agent。

• scroll animation|parallax|GSAP -> scroll-experience（滚动集成）
• react|next|frontend -> frontend-developer（React 集成）
• performance|slow|fps -> performance-engineer（3D 性能优化）
• product page|landing|marketing -> frontend-design（带 3D 的产品落地页）

产品配置器

技能：3d-web-experience、frontend-developer、frontend-design

工作流：

1. Prepare 3D product model
2. Set up React Three Fiber scene
3. Add interactivity (colors, variants)
4. Integrate with product page
5. Optimize for mobile
6. Add fallback images

沉浸式作品集

技能：3d-web-experience、scroll-experience、interactive-portfolio

工作流：

1. Design 3D scene concept
2. Build scene in Spline or R3F
3. Add scroll-driven animations
4. Integrate with portfolio sections
5. Ensure mobile fallback
6. Optimize performance

相关技能

适合搭配使用：scroll-experience、interactive-portfolio、frontend-developer、frontend-design

适用场景

• 在网页中添加可导航的产品模型或配置器，同时保留常规产品和购买控件。
• 诊断现有 Three.js/R3F 场景中的加载、帧耗时、资源大小或输入问题。
• 根据交互、部署和维护需求，在设计制作的 Spline 场景与代码管理的场景之间进行选择。
• 规划与滚动关联的作品集场景，并提供易访问的静态替代方案和减少动态效果的路径。如果深度无助于用户完成任务，优先使用常规 DOM 内容。

局限性

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境进行验证、测试或专家审查的替代品。
• 资源和依赖项是项目的前置条件，并非此技能提供的内容。请将示例 Spline 场景 URL 替换为获准使用的资源；不要将占位符视为可用场景。
• 使用已安装的 CLI 版本和实际目标设备，验证压缩／解码器的兼容性及视觉质量。请参阅 glTF Transform CLI。
• 加载、运行时故障、易访问的 DOM 控件和减少动态效果都需要分别检查；仅渲染 Canvas 并不能证明易访问性或性能达标。