在页面中落地真实 3D 物体:Skills 仓库 webgl-3d-object 技能实战指南(Three.js PBR 几何、光照与运镜)
在页面中落地真实 3D 物体:Skills 仓库 webgl-3d-object 技能实战指南(Three.js PBR 几何、光照与运镜)
导读
webgl-3d-object 是 Skills 仓库(README.md)中 web-design 分类下专门用于"在网页里放一个真实 3D 物体"的 Agent 技能。它解决的核心问题是:当 Hero 区、功能块或产品展示需要真正的几何体、物理光照、高光与边缘,而 CSS 3D 变换、SVG 假象或渐变平面都不够用时,如何用 Three.js 快速搭建一个具备透视相机、PBR 材质、多光源、柔和旋转与浮动动画的刻面多面体。读完本文,你将掌握该技能在 SKILL.md 中定义的完整实现配方:容器 HTML/CSS、可参数化的 Three.js 初始化函数、材质/光照/运动三套默认值,以及一套可验证的快速检查清单。
技能定位:什么时候该用真实 WebGL 3D
在开始写代码之前,先明确该技能的触发条件。根据 SKILL.md 的 "Use When" 一节,它适用于以下场景:
- Hero、功能块或产品时刻需要一个强有力的单个 3D 物体——注意是"一个主角",不是一堆散落的装饰物;
- 视觉上需要体现真实的几何结构、光照、高光与边缘,让用户能"看出"这是个立体物件;
- 一个刻面(faceted)网格需要在页面布局内轻微旋转或悬浮,成为页面的视觉锚点;
- 当 CSS transforms、SVG 假象或扁平渐变已经不够用时,才切换到 WebGL——这既是使用条件,也是一种克制。
从仓库结构看,该技能被 README.md 归类到 "WebGL, canvas, and 3D" 分组(与 threejs、globe-gl、cobejs、webgl-laser 并列),其 demo 目录(demo/PROMPT.md)以 "PulsoApps | Tu app lista en 5 días." 定价页为参考,把 3D 物体作为首屏的视觉主角,用来支撑"5 天交付 App"的强转化叙事。这印证了该技能的典型用法:3D 物体是页面主视觉,服务于品牌情绪与转化,而非自娱自乐的特效。
七条硬性规则:真实几何 + PBR + 多光源
SKILL.md 的 "Rules" 定义了不可妥协的实现边界,Agent 在生成代码时必须逐条满足:
- 使用真实 3D 几何:
IcosahedronGeometry(二十面体)、DodecahedronGeometry(十二面体)、BoxGeometry(立方体)、自定义BufferGeometry,或 glTF 网格;禁止用平面加渐变伪装立体。 - 使用透视相机(PerspectiveCamera),让物体具备真实的深度与比例关系。
- 使用 PBR 材质:
MeshStandardMaterial或MeshPhysicalMaterial。 - 调校
metalness、roughness与emissive,让材质情绪贴合品牌基调。 - 至少一盏方向光 + 环境光或半球光 的灯光组合,才能同时呈现体积感与轮廓。
- 只做变换级动画:轻微旋转、上下浮动(bobbing)或视差(parallax);不移动相机、不加粒子风暴。
- 处理 resize,并在卸载时 dispose 几何体、材质与渲染器。
这七条规则的顺序本身就是一条实现链路:几何 → 相机 → 材质 → 参数调校 → 光照 → 动画 → 资源生命周期。后文的所有代码与默认值都围绕它们展开。
容器搭建:HTML 与 CSS 结构
该技能用两层结构把 3D 画布钉在页面布局中:外层 shell 负责占位与比例,内层 canvas 绝对填充。这样画布可以像一张图片一样参与文档流,且 resize 时由 CSS 决定尺寸、JS 只负责同步渲染器视口。
<div class="webgl-object-shell">
<canvas class="webgl-object-canvas" data-webgl-3d-object></canvas>
</div>
.webgl-object-shell {
position: relative;
width: min(100%, 720px);
aspect-ratio: 1 / 1;
}
.webgl-object-canvas {
position: absolute;
inset: 0;
width: 100%;
height: 100%;
display: block;
}
两个值得注意的细节:
width: min(100%, 720px)让容器在窄屏上收缩、在宽屏上封顶,避免画布无限放大;aspect-ratio: 1 / 1保证正方形取景,与后文相机aspect的初始化逻辑一致。data-webgl-3d-object是技能约定的挂载锚点,JS 通过document.querySelector("[data-webgl-3d-object]")定位画布,符合仓库"portable by default"的文件夹技能约定(见 README.md 的 Folder contract),让同一份脚本可以复用到任意页面。
Three.js 物体配方:从渲染器到清理的完整实现
SKILL.md 给出了一个可直接复制的 initWebGL3DObject 工厂函数,它接受 canvas 与可覆盖默认值的 options 对象,返回一个清理函数。下面按职责拆解各段。
1. 渲染器:透明背景 + ACES 色调映射
import * as THREE from "three";
function initWebGL3DObject(canvas, options = {}) {
if (!canvas) return () => {};
const renderer = new THREE.WebGLRenderer({
canvas,
antialias: true,
alpha: true,
});
renderer.setClearColor(0x000000, 0);
renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, options.maxDpr || 1.75));
renderer.outputColorSpace = THREE.SRGBColorSpace;
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = options.exposure || 1.05;
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
要点解析:
alpha: true+setClearColor(0x000000, 0)使画布透明,3D 物体直接浮在页面背景之上,与 CSS 布局无缝融合;setPixelRatio用Math.min把 DPR 封顶在1.75(可通过maxDpr覆盖),这是 SKILL.md "Avoid" 一节"移动端高 DPR"警告的具体落地;SRGBColorSpace输出 +ACESFilmicToneMapping+toneMappingExposure让 PBR 材质的高光与明暗更接近电影感,而不是默认的线性硬对比;PCFSoftShadowMap提供柔和的软阴影,配合后文ShadowMaterial在地面形成"接地"的落影。
2. 场景与透视相机
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(38, 1, 0.1, 100);
camera.position.set(0, 0.15, 5.2);
fov: 38 是接近人眼凝视焦点的窄视场,能让物体产生"产品陈列"式的体积感而非夸张的广角透视;aspect 初始为 1(呼应正方形的 shell 容器),在 resize() 中随画布实际宽高实时更新;近/远裁剪面 0.1 / 100 覆盖物体到相机的距离即可。相机固定在 (0, 0.15, 5.2),与后文"只动画化物体的 transform、不移动相机"的规则一致。
3. 几何与 PBR 材质:刻面金属质感
const geometry = new THREE.IcosahedronGeometry(options.radius || 1.35, options.detail || 1);
const material = new THREE.MeshStandardMaterial({
color: options.color || 0x8aa4ff,
metalness: options.metalness ?? 0.48,
roughness: options.roughness ?? 0.34,
emissive: options.emissive || 0x101833,
emissiveIntensity: options.emissiveIntensity ?? 0.22,
flatShading: true,
});
const object = new THREE.Mesh(geometry, material);
object.castShadow = true;
object.receiveShadow = true;
scene.add(object);
代码细节与技能规则的对应关系:
IcosahedronGeometry(radius, detail):detail = 1是刻面感与顶点数的平衡点——面数足够多到呈现球体轮廓,又保留清晰的三角面高光,这正是"faceted hero object"的典型形态;flatShading: true强制逐面法线,让每个三角面独立受光,形成高光闪烁的宝石质感("Material Defaults"一节要求刻面物体必须开启它);MeshStandardMaterial的metalness/roughness/emissive三参数是整套 PBR 观感的控制台,技能为它们定义了专门的默认值区间(见下文表格);- 开启
castShadow / receiveShadow,让物体与地面阴影平面建立真实的明暗关系。
4. 三灯体系:环境光 + 主光 + 轮廓光
const ambient = new THREE.AmbientLight(0xffffff, 0.38);
scene.add(ambient);
const key = new THREE.DirectionalLight(0xffffff, 2.15);
key.position.set(3.4, 4.2, 4.8);
key.castShadow = true;
key.shadow.mapSize.set(1024, 1024);
scene.add(key);
const rim = new THREE.DirectionalLight(options.rimColor || 0x7dd3fc, 0.82);
rim.position.set(-4.2, 1.2, -2.8);
scene.add(rim);
这正是 Rules 第 5 条"至少一盏方向光 + 环境光"的完整形态:
- AmbientLight 0.38:低强度全局填充,只负责让暗部不至于死黑,同时保住阴影的可见性("Lighting Defaults"中"ambient fill 保持低强度"的直接体现);
- 主光 DirectionalLight 2.15:位于物体前上方
(3.4, 4.2, 4.8),是全场最亮光源,负责塑造体积;开启阴影投射,mapSize 1024×1024属于"中等偏保守"的阴影图尺寸,避免移动端开销过大; - 轮廓光 DirectionalLight 0.82:默认冷调
0x7dd3fc(可通过rimColor注入品牌色),从背后左上方(-4.2, 1.2, -2.8)射入,勾勒物体的背光边缘,让刻面轮廓从深色背景中"跳"出来。
5. 接地阴影平面:只有落影、没有实体
const shadowPlane = new THREE.Mesh(
new THREE.PlaneGeometry(5.2, 5.2),
new THREE.ShadowMaterial({ opacity: 0.18 })
);
shadowPlane.position.set(0, -1.65, 0);
shadowPlane.rotation.x = -Math.PI / 2;
shadowPlane.receiveShadow = true;
scene.add(shadowPlane);
ShadowMaterial 只接收阴影、不渲染自身颜色,配合 opacity: 0.18 在物体下方 y = -1.65 处形成一层半透明的"落影",既给了物体空间锚定感,又不遮挡页面内容——完美契合技能"物体不能与前景文案/CTA 抢注意力"的原则。
6. 动画循环:旋转 + 浮动,且尊重 reduced-motion
const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
let rafId = 0;
function resize() {
const width = Math.max(1, canvas.clientWidth);
const height = Math.max(1, canvas.clientHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, options.maxDpr || 1.75));
renderer.setSize(width, height, false);
camera.aspect = width / height;
camera.updateProjectionMatrix();
}
function render(time = 0) {
const t = time * 0.001;
object.rotation.x = -0.16 + Math.sin(t * 0.45) * 0.06;
object.rotation.y = t * 0.28;
object.rotation.z = Math.sin(t * 0.32) * 0.08;
object.position.y = reduceMotion ? 0 : Math.sin(t * 0.8) * 0.08;
renderer.render(scene, camera);
if (!reduceMotion) rafId = requestAnimationFrame(render);
}
Motion Defaults 在代码中的落点:
- 旋转是缓慢、连续、次级的:Y 轴匀速
0.28 rad/s,X/Z 轴只在 ±0.06/±0.08 rad 内做正弦摆动,视觉上是"陈列台上的展示品"而不是"炫技的陀螺"; - 浮动幅度
0.08落在技能规定的0.04–0.12区间内,频率0.8柔和不眩晕; - 若用户开启系统级
prefers-reduced-motion,则浮动归零、渲染单帧静态画面并停止 RAF 循环——这是可访问性硬要求,也写进了 demo 的 fidelity 目标(见 demo/PROMPT.md 的 "keyboard accessible, and stable when reduced motion is enabled")。
7. resize 与卸载清理:资源生命周期的完整闭环
function handleResize() {
cancelAnimationFrame(rafId);
resize();
render();
}
resize();
render();
window.addEventListener("resize", handleResize);
return () => {
cancelAnimationFrame(rafId);
window.removeEventListener("resize", handleResize);
geometry.dispose();
material.dispose();
shadowPlane.geometry.dispose();
shadowPlane.material.dispose();
renderer.dispose();
};
}
这一段对应 Rules 第 7 条,也是整个配方最容易漏掉的部分:
resize()中setSize(width, height, false)的第三个参数false表示不修改 canvas 的 CSS 尺寸(CSS 由.webgl-object-canvas的width/height: 100%控制),仅同步绘图缓冲区与相机纵横比,这是"resize 不拉伸物体"(Quick Checks 第 5 条)的关键;- 清理函数依次回收:RAF 循环、resize 事件监听、物体几何与材质、阴影平面的几何与材质、渲染器 GPU 资源。返回的闭包可直接挂到 SPA 的组件卸载钩子或
pagehide事件上,杜绝 WebGL context 泄漏。
调用示例(与 HTML 中的 data-webgl-3d-object 锚点对接):
const cleanupObject = initWebGL3DObject(
document.querySelector("[data-webgl-3d-object]"),
{
color: 0x8aa4ff,
rimColor: 0x7dd3fc,
metalness: 0.48,
roughness: 0.34,
emissive: 0x101833,
}
);
材质默认值:三种品牌情绪的参数区间
SKILL.md 的 "Material Defaults" 给出了按材质质感分类的参数区间,Agent 应根据页面气质在区间内取值:
| 质感目标 | metalness | roughness | 附加说明 |
|---|---|---|---|
| 高端金属(Premium metal) | 0.45 – 0.7 | 0.25 – 0.45 | 高反光、硬高光,适合科技/奢侈品牌 |
| 柔和陶瓷(Soft ceramic) | 0.0 – 0.15 | 0.38 – 0.62 | 漫反射为主,低金属感,适合温和/消费品牌 |
| 发光科技物体(Glow-tinted tech) | 依上表 | 依上表 | 低强度 emissive + emissiveIntensity: 0.12 – 0.35,让暗部带自发光色调 |
| 刻面物体(Faceted) | — | — | 强制 flatShading: true;平滑产品物体则设 false |
Recipe 中给出的默认 metalness 0.48 / roughness 0.34 / emissive 0x101833 / emissiveIntensity 0.22 正是"高端金属 + 微发光"组合的代表值:深蓝自发光(0x101833)在冷调轮廓光下形成科技感暗部,而非纯黑。
光照默认值:四要素的分工
"Lighting Defaults" 把灯光拆成四个有明确职责的要素:
- 主光(Key light):方向光,位于前上方大角度,是全场最强光源,决定体积与主高光;
- 环境填充(Ambient fill):低强度,只提亮暗部而不削弱阴影对比(Recipe 用 0.38);
- 轮廓光(Rim light):品牌色调或冷色调,从物体背后照射,勾出边缘,让刻面从背景中分离(Recipe 默认
0x7dd3fc冷蓝); - 阴影(Shadows):仅在需要"接地感"时开启,阴影图尺寸保持中等(Recipe 用 1024×1024),避免移动端开销。
运动默认值:克制是美德
- 旋转:慢速、连续、内容从属——动画永远是配角,不能影响前景文案阅读;
- 浮动:Y 轴幅度控制在
0.04 – 0.12单位(Recipe 取 0.08); - 减少动效:检测到
prefers-reduced-motion时渲染静态帧,或仅在直接交互时运行动画; - 相机不动:除非 3D 物体本身就是页面主要交互(如可拖拽的产品查看器),否则不要移动相机——这与 Recipe 中相机位置固定
(0, 0.15, 5.2)的做法互为印证。
Avoid 清单:技能明确禁止的做法
SKILL.md 的 "Avoid" 是反向边界,Agent 生成代码时必须绕开:
- 用 CSS 3D 变换假装 WebGL——没有真实几何就没有体积与高光;
- 需求明确要"真实光照与深度"时仍用无光照(unlit)材质;
- 用带渐变的平面冒充实际几何体;
- 用强 bloom 或大量粒子遮挡物体形体;
- 移动端上使用过高 DPR、超大阴影图或过多光源;
- 让物体与前景文案、CTA 争夺视觉焦点。
结合 demo/PROMPT.md 的 fidelity 目标可看出,这些避免项最终都服务于一条主线:3D 物体是页面的主视觉,但必须保持"艺术指导后的克制"——保真参考页的构图、信息密度与动效克制,而不是用特效淹没内容。
快速检查清单:验收一个合格的 3D 物体
写完代码后,按 "Quick Checks" 逐条验收,全部通过才算完成:
- 物体呈现清晰的形体、边缘、高光与阴影;
- 材质确实使用了
metalness、roughness与可选emissive(而非 MeshBasicMaterial); - 方向光与环境光同时存在;
- 相机是透视相机,而非误用正交相机;
- resize 后物体不变形(依赖
setSize(..., false)与 aspect 同步); - 几何、材质、事件监听、RAF 与渲染器全部被清理(调用返回的 cleanup 函数)。
如何在你的 Agent 工作流中使用该技能
该技能以纯 Markdown 文件夹形式分发(见 README.md 的 "Agent support" 一节),可接入 Codex、Claude Code、Cursor 等工具:
- Codex:在执行页面生成任务前,先加载本技能目录下的 SKILL.md 作为上下文;
- Claude Code:在
CLAUDE.md中引用该技能,或直接把 SKILL.md 作为工作上下文打开; - Cursor:将技能文件夹指向 Cursor rules 或对话上下文,便于随时粘贴其中的可复用代码片段与默认值。
仓库内的配套材料可以进一步加深理解:实现层面以 SKILL.md 为唯一事实来源;落地层面参考 demo/PROMPT.md 的最小化提示词、复刻提示词与 Remix 提示词——其中"Recreate the demo"提示词要求把 3D 物体、PBR 材质、多光源与透视相机作为页面的核心技法,并以 demo/index.html 为视觉与交互基准;数据层面可查看 demo/source.json 了解该技能对应的 Neuform 参考页快照与资源清单。
一句话总结这套技能的心法:用真实的几何与光照,做出页面里的一个"陈列级"物体,然后用最克制的旋转与浮动把它呈现出来——最终让用户记住的是产品,而不是特效本身。
