immersive-3d-web

沉浸式 3D Web

内容整理自官方公开文档（threejs.org/manual、threejs.org/docs、r3f.docs.pmnd.rs、drei.docs.pmnd.rs、gsap.com/docs），并非根据训练数据猜测。提取的是结构，而非照搬文档：包括思维模型、决策规则，以及实践中确实会让这些构建效果大打折扣的失误模式。

为什么要创建此内容

高级 3D 资产展示网站（大胆的首屏动效、随滚动推进的摄像机路径、产品级灯光）使用的是一套规模不大、文档齐全的技术栈——难点不在于寻找 API，而在于要知道五种实现方式中，哪一种能在中端手机上稳定保持 60fps。这项技能会提前帮你做出这些决定。

如何使用

• 开始构建任何新的首屏场景 → 首先阅读 reference/concept-to-form.md，先于所有其他内容，包括 three-core.md。 使用这项技能，很容易构建出技术上出色、却与所在网站毫无关联的 3D 首屏——一个多面体浮在屏幕中央，放在手表品牌、抱石健身房或 SaaS 仪表盘上，看起来都同样“高级”，这恰恰就是问题所在。应先根据网站的实际主题决定物体的形态和运动，再编写几何体代码，而不是反过来。
• 从头开始构建 → 先阅读 reference/three-core.md（思维模型），如果使用 React，再阅读 reference/r3f-drei.md。
• 添加滚动驱动的行为 → 阅读 reference/gsap-scroll.md。
• 场景中有许多重复对象（粒子、人群、数据点），或场景运行缓慢 → 阅读 reference/performance.md。
• 组合首屏／展示场景，或检查常见错误 → 阅读 reference/patterns-and-antipatterns.md——这是综合指南，理解各个部分后再阅读。
• 为现有网站调整样式或添加 3D（而非从零开始构建） → 首先阅读 reference/retrofit.md——其中包含集成策略、哪些内容不能破坏，以及平台特定说明（例如与 GitHub 仓库同步的 Lovable/vite_react_shadcn_ts 项目）。目标是现有代码库时，先读这篇，再读其他内容。
• 为首屏区块添加装饰（背景视频／嵌入式 3D、玻璃卡片、交错入场动效、流体字体），而不是构建 3D 本身 → 阅读 reference/hero-dressing.md。无论背景是 R3F、嵌入式 Spline 场景还是普通视频，都适用——这篇讲的是周围的 CSS／动效层，而不是 3D 层。
• 打磨网站其余部分——导航链接、按钮、卡片——让它看起来像一款完整产品，而不只是首屏演示 → 阅读 reference/micro-interactions.md。适用于全站，而非仅限首屏：导航下划线动画、按钮悬停／按压反馈、光泽扫过效果、倾斜／磁吸式光标跟随卡片、卡片悬停抬升效果，以及为什么这些效果的一致性比任何单一效果都重要。任何使用这项技能的构建都值得做一次这样的检查，不只是有炫酷首屏的项目。
• 处理加载／选中／锁定状态、数字／进度显示、自定义光标、滚动字幕，或一次性的庆祝动画 → 阅读 reference/state-and-feedback.md。反馈与应用状态相关，而非与光标相关——这正是演示（只显示最终状态）与真实产品（必须如实呈现每种状态）的区别。还包含两种渐变边框技术（不透明双背景与 mask-composite 叠加）分别适用的决策规则。

核心心智模型（优先掌握，需要时通过 reference/ 查阅扩展内容）

在做任何事情之前：造型应由主题决定，而非习惯。 icosahedronGeometry/torusGeometry/torusKnotGeometry 是简单易用、总能呈现高级感的默认选择——也正因如此，很容易不加思索地选用，却不去考虑它是否真的适合这个网站的主题。参见 concept-to-form.md。

技术栈： Three.js（WebGL 引擎）→ React Three Fiber / R3F（用于它的声明式 React 渲染器，JSX 与 THREE.* 构造函数一一对应）→ drei（现成的辅助工具：灯光配置、加载器、相机控制）→ GSAP ScrollTrigger（将滚动位置作为相机/对象动画的播放头）。

Three.js 的五种基本元素： Scene（树）、Camera（视点）、Renderer（绘制到画布）、Mesh = Geometry（形状）+ Material（表面）、Light（照明——成本随灯光数量增加，开销从低到高：Ambient/Hemisphere → Directional → Point/Spot → RectArea）。

最重要的一项性能决策： 屏幕上有许多对象 → 它们创建后是否需要独立移动？不需要 → 将几何体合并为一次绘制调用。需要 → 使用 THREE.InstancedMesh。切勿为重复项各创建一个 Mesh。

滚动驱动 3D 的模式： GSAP ScrollTrigger 配合 scrub，将滚动位置转化为动画播放头（self.progress，范围 0→1）；在 onUpdate 中读取该值，并在 R3F 的 useFrame 中将其应用到相机/对象变换上——不要依赖 GSAP 默认的 DOM 补间来处理 Three.js 对象属性。

互补技能： 页面周边部分——排版、颜色、布局以及非 3D UI 的无障碍设计——交给 frontend-design。本技能的范围止于“如何构建/优化 WebGL 层”。

来源说明

直接获取的文档（参见各文件中的来源行）；若某个页面无法访问（例如 R3F+GSAP 滚动教程返回 404），gsap-scroll.md/patterns-and-antipatterns.md 中的模式是对已验证基本功能（ScrollTrigger 文档中的 onUpdate/scrub、R3F 文档中的 useFrame）的明确综合，并已标注为综合内容，而非引用示例。

reference/hero-dressing.md 的来源与本技能其他部分不同：它提炼自真实生产环境中的提示词，并已在该文件中注明。

reference/micro-interactions.md 和 reference/state-and-feedback.md 源自本技能中的实际构建/评审工作，以及在两个真实生产代码库（一个在线金融仪表板和一个个人网站）中独立确认的模式——与 hero-dressing.md 一样，适用相同的说明。

reference/concept-to-form.md 源自本技能在一次会话中完成的四次构建里自行观察到的反模式，由使用者直接命名——并非来自文档或外部代码库；该来源已在文件中注明。