在页面中落地真实 3D 物体:Skills 仓库 webgl-3d-object 技能实战指南(Three.js PBR 几何、光照与运镜)

原创2026-10-09 13:04:251,989 阅读

在页面中落地真实 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-object 技能落地 Demo 预览:将真实 WebGL 物体集成进一个橙色主视觉定价页(PulsoApps)后的页面效果

技能定位:什么时候该用真实 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 在生成代码时必须逐条满足:

  1. 使用真实 3D 几何:IcosahedronGeometry(二十面体)、DodecahedronGeometry(十二面体)、BoxGeometry(立方体)、自定义 BufferGeometry,或 glTF 网格;禁止用平面加渐变伪装立体。
  2. 使用透视相机(PerspectiveCamera),让物体具备真实的深度与比例关系。
  3. 使用 PBR 材质:MeshStandardMaterial 或 MeshPhysicalMaterial。
  4. 调校 metalness、roughness 与 emissive,让材质情绪贴合品牌基调。
  5. 至少一盏方向光 + 环境光或半球光 的灯光组合,才能同时呈现体积感与轮廓。
  6. 只做变换级动画:轻微旋转、上下浮动(bobbing)或视差(parallax);不移动相机、不加粒子风暴。
  7. 处理 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 参考页快照与资源清单。

一句话总结这套技能的心法:用真实的几何与光照,做出页面里的一个"陈列级"物体,然后用最克制的旋转与浮动把它呈现出来——最终让用户记住的是产品,而不是特效本身。

登录后查看全文
Skills