# Threejs 3d Web
> 何时使用
- Skill: `findscripter/threejs-3d-web` (Agent Skill)
- Install (CLI): `npx skillmds@latest add findscripter/threejs-3d-web`
- Raw SKILL.md: https://api.skillmd.com/api/skills/findscripter/threejs-3d-web/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: findscripter (https://skillmd.com/u/findscripter)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/findscripter/threejs-3d-web
---
## 何时使用
为网页带来「第三维度」：交互式 3D 场景、产品配置器、3D 作品集、沉浸式落地页、滚动驱动的 3D 动画。核心心法是「在 3D 真能增强体验时才用，而非炫技」，并始终在视觉冲击与性能、可用性之间取得平衡。
适用：网页内嵌 3D、Three.js / React Three Fiber (R3F) / Spline / WebGL / GLSL、3D 模型(GLB)集成与优化、滚动联动相机/模型。
不该用（负边界）：
- 重度 3D 游戏或物理沙盒 —— 用 Babylon.js / Unity / Godot，而非本技能。
- 后端 3D 渲染、CAD 精密建模、影视级离线渲染。
- 任务与 3D 无关，或仅需 2D 图表/动画（用对应前端可视化技能）。
- 缺少模型资产、目标设备、成功标准等必要输入时，先停下来澄清。
## 步骤
1. 技术选型：按下表与决策树选栈。
- 快速原型/设计师友好 → Spline
- React 应用/复杂场景 → React Three Fiber
- 极致控制/非 React → Three.js 原生
- 游戏/重度 3D → Babylon.js（超出本技能）
| 工具 | 适合 | 学习曲线 | 控制力 |
|------|------|---------|--------|
| Spline | 快速原型、设计师 | 低 | 中 |
| React Three Fiber | React、复杂场景 | 中 | 高 |
| Three.js 原生 | 极致控制、非 React | 高 | 最高 |
| Babylon.js | 游戏、重度 3D | 高 | 最高 |
2. 准备模型管线：Blender 建模 → 降面(网页 < 100K 面) → 烘焙贴图合并材质 → 导出 GLB → Draco + WebP 压缩 → 校验体积(理想 < 5MB)。格式优先 GLB/GLTF（体积最小），其次 OBJ；USDZ 用于 Apple AR。
3. 搭建场景：R3F 用 `
);
}
```
滚动驱动（R3F ScrollControls）：
```jsx
import { ScrollControls, useScroll } from '@react-three/drei';
import { useFrame } from '@react-three/fiber';
import { useRef } from 'react';
function RotatingModel() {
const scroll = useScroll();
const ref = useRef();
useFrame(() => { ref.current.rotation.y = scroll.offset * Math.PI * 2; });
return ...;
}
//
```
GSAP + Three.js 相机随滚动移动：
```javascript
import gsap from 'gsap';
import ScrollTrigger from 'gsap/ScrollTrigger';
gsap.to(camera.position, {
scrollTrigger: { trigger: '.section', scrub: true },
z: 5, y: 2,
});
```
移动端降配 + WebGL 兜底：
```jsx
const isMobile = /iPhone|iPad|Android/i.test(navigator.userAgent);
//
// 无 WebGL 时返回 
```
## 注意事项
性能目标（始终优化，3D 很贵）：
| 设备 | 目标帧率 | 最大三角面 |
|------|---------|-----------|
| 桌面 | 60fps | 500K |
| 移动 | 30-60fps | 100K |
| 低端 | 30fps | 50K |
提速要点：重复物体用 Instances；灯光尽量少（一个 ambientLight + 一个 directionalLight）；用 LOD 分级；模型懒加载。
常见校验项（落地前自查）：
- 【高】3D 内容必须有 loading 指示器：用 `` fallback 或 `useProgress`。
- 【中】必须有 WebGL 兜底：检测 WebGL 支持，不支持时回退静态图。
- 【中】模型必须压缩：用 gltf-transform Draco + 贴图压缩，否则体积过大。
- 【中】OrbitControls 勿吞滚动：设 `enableZoom={false}` 或妥善处理 scroll/touch 事件。
- 【中】移动端 DPR 勿过高：移动端限制 `dpr={1}`。
通用约束：本技能产出不替代环境内的真实测试与专家评审；输入、权限、安全边界或成功标准缺失时，先停下询问。
## 互见
- 滚动动画/视差/GSAP → 滚动体验技能。
- React/Next/前端集成 → frontend 技能。
- 帧率慢/性能瓶颈 → 性能优化技能。
- 带 3D 的产品落地页/营销页 → 落地页设计技能。
- 配套工作流：产品配置器（建模→R3F 场景→颜色/变体交互→接入产品页→移动端优化→兜底图）、沉浸式作品集（场景概念→Spline/R3F 搭建→滚动动画→接入作品集→移动端兜底→性能优化）。
---
采编自 sickn33/antigravity-awesome-skills（MIT）。