3D Web Experience：用 Three.js、React Three Fiber 与 Spline 构建高性能 Web 3D 体验（AAS 实战指南）-开发者社区

AI 技能
AI 插件

【免费下载链接】agentic-awesome-skills

AAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.

项目地址：https://gitcode.com/gh_mirrors/an/agentic-awesome-skills

点击查看免费下载

3D Web Experience 是 AAS（agentic-awesome-skills）技能库中面向 Web 3D 开发的专项技能，它把技术选型、模型管线、滚动动效与性能优化收敛为一套可被 Agent 直接执行的模式化流程。本文以该技能文档为核心骨架，结合仓库中的实际源码与目录证据，系统讲解如何在产品配置器、3D 作品集与沉浸式网站等场景中落地 Three.js / React Three Fiber / Spline / WebGL 技术栈，并给出完整可复制的代码示例与性能验证清单。

技能定位：让 Agent 成为 3D Web 体验架构师

在仓库中，该技能对应两份内容一致的 SKILL.md：skills/3d-web-experience/SKILL.md 与插件版 plugins/agentic-awesome-skills-claude/skills/3d-web-experience/SKILL.md。技能元数据定义了它的职责边界：

角色：3D Web Experience Architect（3D Web 体验架构师）；
风险等级：risk: critical，表示任务复杂且对体验影响大，需要严谨执行；
来源：vibeship-spawner-skills（Apache 2.0），入库日期date_added: 2026-02-27；
能力范围：Three.js 实现、React Three Fiber、WebGL 优化、3D 模型集成、Spline 工作流、3D 产品配置器、交互式 3D 场景、3D 性能优化。

在 data/catalog.json 的索引条目中，该技能被归类为category: "design"，并携带3d / web / experience标签与three / js / react / fiber / spline / webgl / interactive等触发词（triggers），Agent 检索到这些关键词即可命中本技能。技能同时声明了明确的使用边界（见 SKILL.md "Limitations" 部分）：仅当任务清晰匹配上述范围时使用；输出不能替代真实环境下的验证、测试与专家评审；当输入、权限、安全边界或成功标准缺失时应停下来澄清。

技术栈选型：四种 3D 方案的选择决策

技能把选型问题拆成一张对比表与一棵决策树，避免"3D 只是为了炫技"的误区——这与技能开篇"你知道何时 3D 能增强体验、何时只是卖弄"的角色定位一致。

方案对比

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

决策树

需要快速 3D 元素？ └── 是 → Spline └── 否 → 继续 使用 React？ └── 是 → React Three Fiber └── 否 → 继续 需要最高性能/控制力？ └── 是 → Three.js vanilla └── 否 → Spline 或 R3F

Spline：最快的启动路径

Spline 适合把设计师在可视化工具中完成的场景直接嵌入 React 应用，最小编码成本：

import Spline from '@splinetool/react-spline'; export default function Scene() { return ( <Spline scene="https://prod.spline.design/xxx/scene.splinecode" /> ); }

scene属性指向 Spline 编辑器导出的.splinecode场景 URL，组件内部负责加载与渲染，适合快速原型与营销落地页。

React Three Fiber：React 世界的声明式 3D

R3F 让 Three.js 场景以 JSX 声明式书写，模型、灯光、控制器都能以组件形式组织：

import { Canvas } from '@react-three/fiber'; import { OrbitControls, useGLTF } from '@react-three/drei'; function Model() { const { scene } = useGLTF('/model.glb'); return <primitive object={scene} />; } export default function Scene() { return ( <Canvas> <ambientLight /> <Model /> <OrbitControls /> </Canvas> ); }

useGLTF负责加载并缓存 GLB 模型，<primitive object={scene}>把解析出的 three.js 场景对象挂载到场景图中，OrbitControls提供轨道交互。从源码结构看，这套组合也是后续产品配置器与滚动 3D 场景的基础骨架。

3D 模型管线：让资产从 DCC 软件走向 Web

"模型管线"模式解决"如何把资产准备好"的问题，包含格式选型、优化流程与压缩命令。

格式选型

格式	用途	体积
GLB/GLTF	Web 3D 标准	最小
FBX	来自 3D 软件	大
OBJ	简单网格	中
USDZ	Apple AR	中

GLB（GLTF 的二进制封装）是 Web 端的事实标准：单文件、易加载、体积最小；FBX 常见于 Blender/3ds Max/Maya 源资产，需要转换；USDZ 用于苹果 AR Quick Look 场景。

优化管线（六步）

1. 在 Blender 等软件中建模 2. 降低面数（Web 端控制在 10 万面以下） 3. 烘焙贴图（合并材质） 4. 导出为 GLB 5. 用 gltf-transform 压缩 6. 验证文件体积（理想值 < 5MB）

gltf-transform 压缩

# 安装 gltf-transform npm install -g @gltf-transform/cli # 压缩模型 gltf-transform optimize input.glb output.glb \ --compress draco \ --texture-compress webp

--compress draco对网格几何数据启用 Draco 压缩，--texture-compress webp把纹理转成 WebP 以减少贴图体积。这两项是本技能"Validation Checks"中"未压缩 3D 模型（Uncompressed 3D Models）"检查项的推荐修复手段。

在 R3F 中加载并显示进度

结合Suspense与 drei 的useProgress，为 3D 内容提供加载指示器——这直接对应验证清单中 severity 为 HIGH 的 "No 3D Loading Indicator" 检查项：

import { useGLTF, useProgress, Html } from '@react-three/drei'; import { Suspense } from 'react'; function Loader() { const { progress } = useProgress(); return <Html center>{progress.toFixed(0)}%</Html>; } export default function Scene() { return ( <Canvas> <Suspense fallback={<Loader />}> <Model /> </Suspense> </Canvas> ); }

useProgress返回加载百分比，Html把 DOM 内容投射到 3D 场景中居中显示；Suspense在模型未就绪时渲染 fallback。库中 scroll-experience 与 interactive-portfolio 技能均与 3D 场景配合使用，滚动与作品集页面同样需要这一加载反馈模式。

滚动驱动 3D：让页面滚动成为交互输入

"滚动驱动 3D"模式覆盖两种主流实现：R3F 的 ScrollControls 体系，以及 GSAP + ScrollTrigger 方案。

R3F + ScrollControls

import { ScrollControls, useScroll } from '@react-three/drei'; import { useFrame } from '@react-three/fiber'; function RotatingModel() { const scroll = useScroll(); const ref = useRef(); useFrame(() => { // 根据滚动位置旋转 ref.current.rotation.y = scroll.offset * Math.PI * 2; }); return <mesh ref={ref}>...</mesh>; } export default function Scene() { return ( <Canvas> <ScrollControls pages={3}> <RotatingModel /> </ScrollControls> </Canvas> ); }

ScrollControls pages={3}把页面滚动映射为三段虚拟空间，useScroll().offset提供 0～1 的归一化进度，在useFrame每帧回调中驱动模型旋转。注意RotatingModel需配合useRef持有 mesh 引用。

GSAP + Three.js

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

scrollTrigger.scrub: true让动画进度跟随滚动条平滑吸附，trigger: '.section'指定触发元素，实现相机在场景中穿行。

常见滚动效果

相机在场景中穿行（Camera movement through scene）
模型随滚动旋转（Model rotation on scroll）
元素显现/隐藏（Reveal/hide elements）
颜色/材质变化（Color/material changes）
爆炸视图动画（Exploded view animations）

当任务侧重滚动/视差/GSAP 时，技能建议将滚动集成部分委托给 scroll-experience（见下方"协作与委托"）。

3D 性能优化：让 3D 在低端设备上依然流畅

"性能优化"模式强调"始终要做"——3D 是昂贵的渲染路径。技能给出分级性能目标、快速优化手段、移动端检测与回退策略四块内容。

性能目标

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

快速取胜清单

// 1. 重复对象使用 Instancing import { Instances, Instance } from '@react-three/drei'; // 2. 限制灯光数量 <ambientLight intensity={0.5} /> <directionalLight /> // 只保留一盏 // 3. 使用 LOD（细节层次） import { LOD } from 'three'; // 4. 懒加载模型 const Model = lazy(() => import('./Model'));

Instancing 让大量重复网格共享一次 draw call；灯光是逐片元计算成本的大头，减少灯光数量立竿见影；LOD 根据相机距离切换模型精度；React.lazy让模型组件按需加载。

移动端检测

const isMobile = /iPhone|iPad|Android/i.test(navigator.userAgent); <Canvas dpr={isMobile ? 1 : 2} // 移动端降低渲染分辨率 performance={{ min: 0.5 }} // 允许帧率下降 >

dpr（devicePixelRatio）控制渲染分辨率，移动端压到 1 能显著减少 GPU 负载；performance.min: 0.5允许渲染器在帧率紧张时主动降低分辨率。这直接对应验证清单中的 "High DPR on Mobile" 检查项。

回退策略

function Scene() { const [webGLSupported, setWebGLSupported] = useState(true); if (!webGLSupported) { return <img src="/fallback.png" alt="3D preview" />; } return <Canvas onCreated={...} />; }

通过 WebGL 能力检测决定渲染 3D 还是展示静态预览图，保证不支持 WebGL 的设备（老旧浏览器、部分低端机型）依然有可用内容——对应验证清单中的 "No WebGL Fallback" 检查项。技能中同时建议通过限制 DPR、关闭 OrbitControls 缩放等方式避免控制器劫持页面滚动（对应 "OrbitControls Blocking Scroll" 检查项）。

验证检查清单：交付前的自动审查项

技能内置了一套可自动执行的验证检查（Validation Checks），Agent 交付前可逐项核验：

检查项	严重级别	问题信息	修复动作
No 3D Loading Indicator	HIGH	3D 内容缺少加载指示器	用 Suspense + 加载 fallback 或 useProgress 提供加载 UI
No WebGL Fallback	MEDIUM	未对不支持 WebGL 的设备提供回退	添加 WebGL 检测与静态图片回退
Uncompressed 3D Models	MEDIUM	3D 模型可能未优化	用 gltf-transform 的 Draco 与纹理压缩
OrbitControls Blocking Scroll	MEDIUM	OrbitControls 可能捕获滚动事件	设`enableZoom={false}`或正确处理滚动/触摸事件
High DPR on Mobile	MEDIUM	Canvas DPR 对移动端过高	移动端将 DPR 限制为 1 以提升性能

这五条检查项与上文各节代码一一对应，形成"模式执行 → 代码落地 → 自动审查"的闭环，是技能可被 Agent 可靠执行的关键设计。

协作与委托：与仓库其他技能的配合方式

技能声明了明确的委托触发器（Delegation Triggers），遇到超出自身边界的问题时转交更专业的技能：

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

仓库中对应可用的技能包括 scroll-experience、interactive-portfolio、frontend-developer 与 landing-page-generator，它们在 data/catalog.json 中均归入front-end类别。

产品配置器工作流

所需技能：3d-web-experience、frontend、landing-page-design

1. 准备 3D 产品模型 2. 搭建 React Three Fiber 场景 3. 添加交互（颜色、款式变体） 4. 与产品页集成 5. 针对移动端优化 6. 添加回退图片

沉浸式作品集工作流

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

1. 设计 3D 场景概念 2. 在 Spline 或 R3F 中搭建场景 3. 添加滚动驱动动画 4. 与作品集各分区集成 5. 确保移动端回退 6. 优化性能

在仓库的 data/editorial-bundles.json 中，3d-web-experience被编入 web-wizard、web-designer、full-stack-developer、creative-director 等数十个主题包（bundles），说明它作为通用 3D 能力被横向复用于多种开发角色；data/bundles.json 同样收录了该技能。这意味着 Agent 在作品集、落地页、全栈与创意设计等任务上下文中均可自动加载本技能。

触发条件与使用边界

何时使用

当用户提及或暗示以下关键词时触发本技能：

3D website（3D 网站）
three.js
WebGL
react three fiber
3D experience（3D 体验）
spline
product configurator（产品配置器）

限制与前提

仅在任务清晰匹配上述范围时使用本技能；
输出不能替代针对具体环境的验证、测试或专家评审；
当所需输入、权限、安全边界或成功标准缺失时，应停下来向用户澄清，而不是盲目执行。

小结

从技术栈选型、模型管线、滚动驱动 3D 到性能优化与验证清单，3d-web-experience 技能把"Web 3D 开发"压缩成一套 Agent 可执行、可验证、可委托的标准化流程：以 R3F/Three.js/Spline 为渲染基石，以 gltf-transform 为资产压缩手段，以五条验证检查项为交付质量门槛，并通过协作触发词与滚动、作品集、落地页等兄弟技能无缝衔接。对开发者而言，本文的代码骨架可直接用于产品配置器、3D 作品集与沉浸式品牌网站；对 Agent 而言，该技能文档本身就是一份可检索、可引用、可执行的 3D 工程规范。

相关技能：scroll-experience、interactive-portfolio、frontend-developer、landing-page-generator