一个 HTML 文件,为什么能装下一座 3D 世界?

0 阅读27分钟

从浏览器实时渲染、Three.js、程序化生成,到 ChatGPT 辅助开发与 RelayRouter 接口接入的完整实践

有些网页,第一眼看上去不像网页。

雨水打在集装箱上,灯光穿过薄雾,远处的吊机缓慢转动,水面不断反射环境光。鼠标一拖,视角跟着旋转;滚轮一推,镜头就钻进场景深处。更让人意外的是,它不需要安装,也没有一个装满贴图和三维资产的资源目录,双击一个 HTML 文件就能运行。 在这里插入图片描述

下面这张图,就是这类作品常见的视觉形态: 在这里插入图片描述 在这里插入图片描述

很多人第一次看到这种画面,会把注意力放在“文件为什么这么小”。但真正值得拆开的,不是某个数字,而是一套正在变得越来越普及的创作方法:浏览器负责实时渲染,代码负责描述世界,Three.js 负责降低开发门槛,ChatGPT 负责帮助人整理想法和迭代代码,而 RelayRouter 这类兼容接口,则可以把对话能力接进自己的开发流程。

这篇文章不讨论夸张的体积纪录,也不把任何一个工具写成神话。我们只做一件更有用的事:从零解释,一个看起来复杂的 3D 网页究竟是怎样被“写”出来的,以及普通开发者如何做出自己的版本。


一、你下载的不是一座城市,而是一套生成城市的规则

先想象两个文件。 在这里插入图片描述

第一个文件里放着一栋楼的高精度网格、墙面照片、玻璃贴图、法线纹理、金属粗糙度信息以及环境声音。它记录的是“成品”,信息越精细,文件通常越大。

第二个文件只写规则:

  • 在坐标 (0, 0, 0) 放一个长方体;
  • 长宽高分别是 8、4、3;
  • 表面使用偏蓝的金属材质;
  • 沿 X 轴复制 12 次,每次间隔 9 个单位;
  • 每隔 3 个物体改变一次颜色;
  • 在上方生成 2 层,第二层略微错位;
  • 给场景加入雾、雨点、暖色灯光和湿润地面的反射。

它没有保存十二个集装箱的每个细节,而是保存了“怎样生成十二个集装箱”。浏览器读完规则,再利用本机的图形能力现场搭建画面。

这就是程序化生成最直观的价值:把大量重复数据,换成少量可执行规则。

规则并不只负责物体数量。地形可以由噪声函数生成,窗户可以按概率点亮,雨点可以在触地后回到天空,水面的起伏可以由时间和波函数共同决定,甚至简单的提示音也能用振荡器在运行时合成。一个看似丰富的场景,背后往往只是若干组参数、循环、随机数和着色计算。

这并不意味着“代码一定比资产小”。如果要表现写实人物、复杂动物、精细机械或大量独特物件,专业制作的三维资产仍然更合适。程序化方法擅长的是另一类问题:重复结构、抽象空间、建筑群、粒子、自然现象、低多边形物体以及强调氛围而非微观细节的场景。

所以,理解小体积 3D 网页的第一步,不是研究怎样把图片压得更狠,而是先问自己:

哪些信息必须保存,哪些信息可以在打开页面之后再生成?

这个问题一旦想清楚,很多原本需要几百个文件的画面,就会变成几十个函数。


二、浏览器到底是怎样把代码变成 3D 画面的

浏览器里的 3D 画面,本质上不是一张不断替换的图片,而是一连串高速计算的结果。 在这里插入图片描述

一帧画面大致经历下面几层:

  1. JavaScript 创建场景中的物体与规则;
  2. 几何数据被拆成显卡容易处理的三角形;
  3. 摄像机决定从哪里看、能看见多大范围;
  4. 材质决定表面如何响应光线;
  5. 灯光、阴影、雾和后期效果共同决定氛围;
  6. 浏览器把计算结果绘制到 <canvas>;
  7. 下一帧到来之前,程序更新物体位置、粒子状态和时间参数。

底层的 WebGL 能让网页调用图形硬件,但它的接口偏底层。开发者需要处理缓冲区、矩阵、着色器、纹理状态和大量图形学细节。对于想快速搭场景的人来说,这些工作会遮住真正的创作目标。

Three.js 的作用,就是在 WebGL 之上提供一层更容易理解的表达方式。你不再需要先手写一整套投影矩阵,才把一个立方体放进画面;你可以直接创建几何体、材质、网格、灯光和摄像机:

const geometry = new THREE.BoxGeometry(4, 2, 2);
const material = new THREE.MeshStandardMaterial({ color: 0x315d73 });
const container = new THREE.Mesh(geometry, material);
scene.add(container);

这一小段代码背后仍然会生成顶点、三角形和渲染指令,只是复杂度被库收起来了。

可以把一个 Three.js 项目理解成六个核心角色:

角色负责什么常见对象
场景收纳所有可见与不可见对象Scene
摄像机决定观察位置和透视关系PerspectiveCamera
渲染器把场景绘制到画布WebGLRenderer
几何体定义物体的形状BoxGeometry、PlaneGeometry
材质定义物体表面的视觉特征MeshStandardMaterial
灯光提供明暗、方向和氛围DirectionalLight、PointLight

此外还有控制器、粒子、动画混合器、加载器、后期处理、着色器等工具。但初学时不必一次吃透。一个最小 3D 网页,只要场景、摄像机、渲染器和一个带材质的几何体就能运行。

真正让画面“像作品”的,通常不是物体数量,而是关系是否成立:镜头是否有主次,光从哪里来,雾把远景压到什么程度,冷暖颜色怎样分布,地面是否给出了空间尺度,动画是否让环境有呼吸感。Three.js 解决的是“能画出来”,审美和叙事仍然需要人来决定。


三、体积为什么能降下来:程序化几何、材质、粒子与声音

如果把一个网页 3D 场景拆开,最占空间的通常不是控制逻辑,而是三类东西:模型、图片和音频。想做轻量化,关键就是减少这三类外部资产,同时控制运行时成本。 在这里插入图片描述

1. 用基础几何拼出复杂结构

集装箱、楼房、道路、栏杆、桥墩、路灯和吊机,都可以从长方体、圆柱、平面与线段开始。

例如,一座吊机不一定要使用精细建模文件。教学演示里,可以用四根立柱、一根横梁、几根斜撑和一个沿导轨移动的小车表达。单个部件很简单,但比例、颜色和轮廓组合正确后,观众会自动识别它。

这种方法的重点不是把现实物体逐毫米还原,而是抓住视觉特征:

  • 集装箱要有规律的纵向凹槽;
  • 吊机要有明显的门架轮廓和悬臂;
  • 城市要有高低错落与窗口节奏;
  • 桥梁要给出连续的受力结构;
  • 船只要有船体、舱室和航行灯的层级。

2. 用 Canvas 动态画贴图

不引用外部图片,不等于物体只能是纯色。浏览器可以先创建一张离屏画布,再用代码画出条纹、锈迹、编号、窗格、路面划线或渐变,最后把这张画布作为材质纹理交给 Three.js。

function makeStripeTexture() {
  const canvas = document.createElement('canvas');
  canvas.width = 256;
  canvas.height = 256;
  const ctx = canvas.getContext('2d');

  ctx.fillStyle = '#28495b';
  ctx.fillRect(0, 0, 256, 256);

  ctx.strokeStyle = 'rgba(255,255,255,.12)';
  ctx.lineWidth = 6;
  for (let x = 12; x < 256; x += 22) {
    ctx.beginPath();
    ctx.moveTo(x, 0);
    ctx.lineTo(x, 256);
    ctx.stroke();
  }

  return new THREE.CanvasTexture(canvas);
}

这张纹理没有随文件下载,而是在页面打开时生成。它适合规则性较强、允许抽象化的表面。

3. 用粒子表达雨、雪、火花和灰尘

雨点不需要逐个建成小圆柱。更常见的做法是把大量点放进一个几何缓冲区,每帧只更新它们的位置。雨滴落到地面后,重新回到上方继续下落。

数量很多时,还要避免给每一个粒子都创建独立对象。共享几何和材质、批量更新缓冲区,能显著减少运行时开销。

4. 用着色计算替代一部分纹理

水面波纹、扫描线、发光边缘、云层扰动和颜色渐变,可以在着色阶段计算。它们不一定占用大量文件空间,但会消耗显卡时间。因此,文件小并不等于运行轻。开发时必须同时看两个预算:下载体积和每帧计算量。

5. 用 Web Audio 生成简单声音

短促提示音、环境低频、点击声和简单节奏,可以由浏览器的音频节点生成。复杂配乐和真实环境录音仍然应该使用音频文件,但交互反馈完全可以代码合成。

最后还要提醒一个经常被忽略的事实:轻量化不是比赛。为了少几十 KB 而把代码压成无法维护的一团,往往得不偿失。更合理的顺序是先做出可维护、可复用的版本,再通过压缩、复用、实例化和按需加载逐步减小体积。


四、先做一个能运行的单文件 3D 港口

下面这份示例只使用基础几何和粒子,不加载图片、三维资产或音频。为了让代码容易阅读,教学版本通过公共 CDN 引入 Three.js 和视角控制器;正式交付时,可以把依赖下载并打包进最终 HTML,后文会讲到。 在这里插入图片描述

把下面内容保存为 harbor.html,用现代浏览器打开即可。鼠标拖动旋转视角,滚轮缩放。

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>程序化雨夜港口</title>
  <style>
    * { box-sizing: border-box; }
    html, body { width: 100%; height: 100%; margin: 0; overflow: hidden; }
    body { background: #071018; font-family: system-ui, sans-serif; }
    #tip {
      position: fixed; left: 20px; top: 18px; z-index: 2;
      padding: 10px 14px; color: #dcebf2;
      background: rgba(3, 10, 16, .55); border: 1px solid rgba(255,255,255,.12);
      border-radius: 12px; backdrop-filter: blur(10px);
    }
    canvas { display: block; }
  </style>
  <script type="importmap">
  {
    "imports": {
      "three": "https://cdn.jsdelivr.net/npm/three@0.169.0/build/three.module.js",
      "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.169.0/examples/jsm/"
    }
  }
  </script>
</head>
<body>
  <div id="tip">拖动旋转 · 滚轮缩放</div>
  <script type="module">
    import * as THREE from 'three';
    import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

    const scene = new THREE.Scene();
    scene.background = new THREE.Color(0x071018);
    scene.fog = new THREE.FogExp2(0x071018, 0.018);

    const camera = new THREE.PerspectiveCamera(55, innerWidth / innerHeight, 0.1, 300);
    camera.position.set(34, 22, 42);

    const renderer = new THREE.WebGLRenderer({ antialias: true });
    renderer.setSize(innerWidth, innerHeight);
    renderer.setPixelRatio(Math.min(devicePixelRatio, 1.6));
    renderer.shadowMap.enabled = true;
    renderer.shadowMap.type = THREE.PCFSoftShadowMap;
    renderer.toneMapping = THREE.ACESFilmicToneMapping;
    renderer.toneMappingExposure = 1.15;
    document.body.appendChild(renderer.domElement);

    const controls = new OrbitControls(camera, renderer.domElement);
    controls.target.set(0, 5, 0);
    controls.enableDamping = true;
    controls.maxPolarAngle = Math.PI * 0.49;
    controls.minDistance = 12;
    controls.maxDistance = 90;

    scene.add(new THREE.HemisphereLight(0x6d91aa, 0x101820, 1.5));

    const moon = new THREE.DirectionalLight(0xb7d7ff, 2.4);
    moon.position.set(-18, 28, 12);
    moon.castShadow = true;
    scene.add(moon);

    const warmLight = new THREE.PointLight(0xffa34d, 90, 42, 2);
    warmLight.position.set(8, 10, -8);
    scene.add(warmLight);

    // 湿润地面
    const ground = new THREE.Mesh(
      new THREE.PlaneGeometry(130, 130),
      new THREE.MeshStandardMaterial({
        color: 0x14232a, roughness: 0.28, metalness: 0.45
      })
    );
    ground.rotation.x = -Math.PI / 2;
    ground.receiveShadow = true;
    scene.add(ground);

    // 集装箱工厂:统一尺寸,只改变位置和颜色
    const colors = [0x244d5a, 0x6a3e2d, 0x304b38, 0x4c4a42];
    function createContainer(x, y, z, color) {
      const group = new THREE.Group();
      const box = new THREE.Mesh(
        new THREE.BoxGeometry(7.4, 2.7, 2.9),
        new THREE.MeshStandardMaterial({ color, roughness: 0.72, metalness: 0.28 })
      );
      box.castShadow = true;
      box.receiveShadow = true;
      group.add(box);

      const ribMat = new THREE.MeshStandardMaterial({ color: 0x11191d, roughness: 0.8 });
      for (let i = -3; i <= 3; i++) {
        const rib = new THREE.Mesh(new THREE.BoxGeometry(0.08, 2.45, 2.96), ribMat);
        rib.position.x = i;
        group.add(rib);
      }
      group.position.set(x, y, z);
      scene.add(group);
    }

    for (let row = 0; row < 5; row++) {
      for (let col = 0; col < 6; col++) {
        const x = -22 + col * 8.1;
        const z = -16 + row * 7;
        const level = (row + col) % 3 === 0 ? 2 : 1;
        for (let n = 0; n < level; n++) {
          createContainer(x, 1.4 + n * 2.8, z, colors[(row + col + n) % colors.length]);
        }
      }
    }

    // 简化吊机:只抓轮廓特征
    const steel = new THREE.MeshStandardMaterial({ color: 0x26343b, metalness: 0.75, roughness: 0.35 });
    function beam(w, h, d, x, y, z, rz = 0) {
      const mesh = new THREE.Mesh(new THREE.BoxGeometry(w, h, d), steel);
      mesh.position.set(x, y, z);
      mesh.rotation.z = rz;
      mesh.castShadow = true;
      scene.add(mesh);
      return mesh;
    }
    beam(1, 18, 1, -10, 9, -24);
    beam(1, 18, 1, 10, 9, -24);
    beam(24, 1.2, 1.4, 0, 17.5, -24);
    beam(13, .8, .8, 15, 17.5, -24);
    beam(21, .45, .45, 0, 11, -24, 0.72);
    beam(21, .45, .45, 0, 11, -24, -0.72);

    // 雨点:一个 Points 对象承载全部粒子
    const rainCount = 5000;
    const rainPositions = new Float32Array(rainCount * 3);
    for (let i = 0; i < rainCount; i++) {
      rainPositions[i * 3] = (Math.random() - .5) * 110;
      rainPositions[i * 3 + 1] = Math.random() * 48;
      rainPositions[i * 3 + 2] = (Math.random() - .5) * 110;
    }
    const rainGeometry = new THREE.BufferGeometry();
    rainGeometry.setAttribute('position', new THREE.BufferAttribute(rainPositions, 3));
    const rain = new THREE.Points(
      rainGeometry,
      new THREE.PointsMaterial({ color: 0xa8c9d8, size: 0.08, transparent: true, opacity: .65 })
    );
    scene.add(rain);

    const clock = new THREE.Clock();
    function animate() {
      requestAnimationFrame(animate);
      const dt = Math.min(clock.getDelta(), 0.033);
      const p = rainGeometry.attributes.position.array;
      for (let i = 0; i < rainCount; i++) {
        const y = i * 3 + 1;
        p[y] -= 19 * dt;
        if (p[y] < 0) p[y] = 40 + Math.random() * 8;
      }
      rainGeometry.attributes.position.needsUpdate = true;
      controls.update();
      renderer.render(scene, camera);
    }
    animate();

    addEventListener('resize', () => {
      camera.aspect = innerWidth / innerHeight;
      camera.updateProjectionMatrix();
      renderer.setSize(innerWidth, innerHeight);
    });
  </script>
</body>
</html>

这个版本并不追求复杂玩法,但已经包含了一个完整场景的骨架:镜头控制、灯光、雾、材质、重复建筑、结构物、粒子与动画循环。

如果打开后出现黑屏,先不要同时修改十处代码。按下面顺序排查:

  1. 打开浏览器开发者工具,看控制台第一条红色错误;
  2. 确认电脑能够访问脚本地址;
  3. 确认浏览器支持 importmap;
  4. 暂时注释雨点循环,判断是否是性能问题;
  5. 把摄像机改回示例位置,避免镜头落在物体内部;
  6. 把雾密度调低,避免整个场景被雾覆盖。

教学代码通过 CDN 获取依赖,因此它是“单个页面文件”,但不是完全离线。若需要制作真正可离线分发的单文件,可以使用构建工具把 Three.js、控制器和自己的脚本打包成一个 app.js,压缩后再嵌回 HTML:

npx esbuild src/main.js --bundle --minify --outfile=dist/app.js

构建阶段可以用一个模板把 app.js 的内容写入 <script>。最后交付物仍然只有一个 HTML,但开发阶段保留了清晰的模块结构。单文件应当是交付格式,而不是从第一天就把所有代码塞在一起的开发方式。


五、ChatGPT 真正适合做的,不是“一句话生成成品”

不少人第一次用 ChatGPT 写 3D 网页,会给出一句很宏大的要求:做一座未来城市,要逼真、要能玩、要流畅、要一个文件。然后等待一次输出直接成为成品。 在这里插入图片描述

这样做偶尔能得到有趣的草稿,但很难稳定。原因并不神秘:需求同时包含美术、镜头、交互、图形性能、代码结构和兼容性,任何一个部分描述不清,结果就会向不可控的方向漂移。

更有效的做法,是让 ChatGPT 参与一条分阶段的开发链路。

阶段一:把画面拆成可编程对象

不要只说“做一个港口”,而要先列出:

  • 地面:湿润、深灰、有反光,但不做昂贵的实时镜面;
  • 集装箱:四种颜色、两种堆叠高度、共用几何;
  • 吊机:只保留门架、横梁、斜撑和移动小车;
  • 雨:粒子表现,限制数量;
  • 雾:拉开前中后景;
  • 灯:一个主方向光,若干暖色点光;
  • 镜头:初始位置、观察目标、可缩放范围;
  • 性能:普通笔记本优先,像素比设置上限。

这种清单会把“审美愿望”转成“工程对象”。

阶段二:要求先交付骨架

第一轮只要场景、相机、渲染器、控制器和几个占位几何体。确认镜头和比例之后,再加灯光;确认灯光之后,再加雨和细节。

一次只增加一个变量,出错时才知道问题来自哪里。

阶段三:让代码保持组件边界

一个可维护的场景,至少应该把下面这些职责分开:

createScene()
createLighting()
createGround()
createContainerYard()
createCrane()
createRainSystem()
createControls()
update(deltaTime)

后续你要把吊机加高、调整雨速或关闭阴影,不必在几百行代码里寻找某个匿名变量。

阶段四:让 ChatGPT 根据证据修,而不是凭感觉重写

最有价值的输入往往不是“再高级一点”,而是这些具体证据:

  • 固定机位截图;
  • 浏览器控制台报错;
  • 性能面板中的帧率和绘制次数;
  • 哪台电脑、哪个浏览器出现问题;
  • 修改前后对比;
  • 你认为最影响画面的三个问题。

可以直接使用下面这段提示词:

你是这个 Three.js 项目的技术美术与前端审查者。

目标:在不增加外部图片和三维资产的前提下,改善画面层次与运行稳定性。

请按以下顺序工作:
1. 先根据截图判断构图、尺度、光照、雾、色彩和视觉焦点的问题;
2. 再根据控制台信息判断代码错误;
3. 每轮只提出 3 个优先级最高的修改;
4. 说明每个修改会影响哪个函数、预期改善是什么、可能带来什么性能代价;
5. 给出最小代码补丁,不要无关重写;
6. 保留 createScene、createLighting、createRainSystem 等现有组件边界。

ChatGPT 在这里扮演的不是自动售货机,而是结对开发者:帮你拆问题、补盲区、解释报错、生成重复代码,再由你决定取舍。


六、AI、ChatGPT 与 RelayRouter,三者应该怎样理解

在这里插入图片描述

这三个词经常出现在同一段讨论里,但它们并不是同一层级。

AI 是更大的能力集合。文本理解、代码协助、图像处理、语音交互、数据分析,都可以放在这个范围里。

ChatGPT 是人们直接使用的一种对话式产品。你在对话框里描述场景、贴入报错、要求修改代码,得到的就是一次面向人的交互体验。

RelayRouter 在开发场景里更接近接口服务层。它提供兼容的调用方式,让程序通过 HTTP 请求提交消息,再接收结构化结果。开发者关心的是地址、鉴权、请求体、响应、错误处理和用量记录,而不是手工复制粘贴每一轮对话。

可以把关系写成一条很朴素的链路:

人的需求
   ↓
ChatGPT:用于讨论、规划、生成与修改
   ↓
开发者把成熟流程写进自己的应用
   ↓
RelayRouter:提供程序化调用入口
   ↓
AI 能力返回结构化内容
   ↓
网页根据结果更新文案、参数或 3D 场景

它们不是互相替代的关系。ChatGPT 适合人直接工作;RelayRouter 适合代码发起请求;AI 是两者背后的能力范畴。对于 3D 网页开发,一个常见流程是:先在 ChatGPT 里反复讨论画面和代码,等提示结构稳定后,再通过接口把“生成场景参数”“解释报错”“给出下一轮修改建议”等固定任务接进内部工具。

本文会用到三个地址:

地址用途
https://api.relayrouter.app服务根地址,用来识别域名
https://api.relayrouter.app/v1带版本前缀的基础地址
https://api.relayrouter.app/v1/chat/completions本文发送对话请求的完整路径

需要特别强调:不要把 API Key 直接写进公开 HTML。

HTML 会被下载到访问者电脑,开发者工具也能看到前端请求。只要密钥出现在浏览器端,就不能再把它当成秘密。正确做法是增加自己的服务端:浏览器只访问你自己的 /api/scene-plan,服务端从环境变量读取密钥,再请求 RelayRouter。

这不是多此一举。服务端还可以顺便完成限流、输入长度检查、日志脱敏、超时控制和错误格式统一。


七、把 RelayRouter 接进项目:从最小请求到场景参数

下面用 Node.js 写一个最小服务端。它接收网页传来的场景描述,请求对话接口,并要求返回一份 JSON 场景方案。 在这里插入图片描述

第一步:准备项目

mkdir scene-assistant
cd scene-assistant
npm init -y
npm install express dotenv

创建 .env:

RELAYROUTER_API_KEY=替换为你自己的密钥
CHAT_MODEL=替换为控制台中可用的调用标识
PORT=3000

把 .env 加入 .gitignore,不要提交到公开仓库:

node_modules/
.env

第二步:创建服务端

新建 server.js:

require('dotenv').config();
const express = require('express');

const app = express();
app.use(express.json({ limit: '32kb' }));
app.use(express.static('public'));

const CHAT_URL = 'https://api.relayrouter.app/v1/chat/completions';

app.post('/api/scene-plan', async (req, res) => {
  const description = String(req.body?.description || '').trim();

  if (!description) {
    return res.status(400).json({ error: '请填写场景描述' });
  }
  if (description.length > 2000) {
    return res.status(400).json({ error: '场景描述过长,请压缩到 2000 字以内' });
  }

  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 30_000);

  try {
    const response = await fetch(CHAT_URL, {
      method: 'POST',
      signal: controller.signal,
      headers: {
        'Authorization': `Bearer ${process.env.RELAYROUTER_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: process.env.CHAT_MODEL,
        stream: false,
        temperature: 0.35,
        messages: [
          {
            role: 'system',
            content: [
              '你是一名 Three.js 场景规划助手。',
              '只返回合法 JSON,不要 Markdown,不要解释。',
              '字段固定为:background、fogColor、fogDensity、rainCount、',
              'containerRows、containerColumns、warmLightColor、',
              'cameraPosition、notes。',
              '颜色使用十六进制字符串;cameraPosition 是三个数字的数组;',
              'rainCount 范围 0 到 8000;行列数量范围 1 到 12。'
            ].join('')
          },
          {
            role: 'user',
            content: `请把下面描述转换为场景参数:${description}`
          }
        ]
      })
    });

    const rawText = await response.text();

    if (!response.ok) {
      console.error('RelayRouter error:', response.status, rawText.slice(0, 500));
      return res.status(502).json({
        error: '上游请求失败',
        status: response.status
      });
    }

    const data = JSON.parse(rawText);
    const content = data.choices?.[0]?.message?.content;
    if (!content) {
      return res.status(502).json({ error: '响应中没有可用内容' });
    }

    let plan;
    try {
      plan = JSON.parse(content);
    } catch {
      return res.status(502).json({ error: '返回内容不是合法 JSON' });
    }

    // 服务端再次校验,不直接相信生成结果
    plan.rainCount = Math.max(0, Math.min(8000, Number(plan.rainCount) || 0));
    plan.containerRows = Math.max(1, Math.min(12, Number(plan.containerRows) || 4));
    plan.containerColumns = Math.max(1, Math.min(12, Number(plan.containerColumns) || 6));

    return res.json(plan);
  } catch (error) {
    const message = error.name === 'AbortError' ? '请求超时' : '服务器内部错误';
    console.error(error);
    return res.status(500).json({ error: message });
  } finally {
    clearTimeout(timer);
  }
});

app.listen(process.env.PORT || 3000, () => {
  console.log(`Server running at http://localhost:${process.env.PORT || 3000}`);
});

这里有几个细节值得保留:

  • 密钥来自服务端环境变量;
  • 输入长度有限制;
  • 请求设置了超时;
  • 上游错误不会原样暴露给浏览器;
  • 返回内容必须经过 JSON 解析;
  • 数值在服务端被限制到合理范围;
  • 日志只截取一小段错误信息,避免无意记录完整输入。

第三步:在网页端调用自己的服务

在 public/index.html 中加入一个输入框和按钮,然后调用本地接口:

<textarea id="idea" placeholder="例如:雨更密,雾偏蓝,暖灯减少,集装箱更稀疏"></textarea>
<button id="apply">生成场景参数</button>
<pre id="result"></pre>

<script>
  const button = document.querySelector('#apply');
  const result = document.querySelector('#result');

  button.addEventListener('click', async () => {
    button.disabled = true;
    result.textContent = '正在生成参数…';

    try {
      const response = await fetch('/api/scene-plan', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          description: document.querySelector('#idea').value
        })
      });

      const data = await response.json();
      if (!response.ok) throw new Error(data.error || '请求失败');

      result.textContent = JSON.stringify(data, null, 2);
      applyScenePlan(data);
    } catch (error) {
      result.textContent = `错误:${error.message}`;
    } finally {
      button.disabled = false;
    }
  });

  function applyScenePlan(plan) {
    // 不执行返回的代码,只读取经过允许的参数
    scene.background.set(plan.background);
    scene.fog.color.set(plan.fogColor);
    scene.fog.density = Number(plan.fogDensity) || 0.018;
    warmLight.color.set(plan.warmLightColor);

    if (Array.isArray(plan.cameraPosition) && plan.cameraPosition.length === 3) {
      camera.position.set(...plan.cameraPosition.map(Number));
    }

    // rainCount、行列数量涉及缓冲区和对象重建,
    // 实际项目中应调用独立的 rebuildRain / rebuildYard 函数。
  }
</script>

这里最重要的一句,是注释里的“不执行返回的代码”。

如果把生成内容直接塞进 eval(),或者当作脚本插入页面,相当于允许远端文本控制你的网页。更稳妥的设计,是只接受一份字段固定的 JSON,然后由本地代码把允许的参数映射到场景对象。

这也是把 AI 能力接进产品时非常实用的原则:

让它提供建议和参数,不让它越过边界直接获得执行权。

三个地址在代码里怎样组织

如果项目里有多处调用,可以保留基础地址:

const RELAYROUTER_ORIGIN = 'https://api.relayrouter.app';
const RELAYROUTER_BASE_URL = `${RELAYROUTER_ORIGIN}/v1`;
const CHAT_URL = `${RELAYROUTER_BASE_URL}/chat/completions`;

最终请求的仍然是:

https://api.relayrouter.app/v1/chat/completions

如果只调用这一个接口,直接保存完整地址反而更清楚。工程设计不必为了“看起来高级”增加抽象层。


八、怎样把第一版继续打磨,而不是不断推倒重来

一个 3D 网页从“能打开”到“看起来完整”,中间往往隔着多轮微调。最容易浪费时间的方式,是每次觉得不好看就重新生成整份代码。代码越写越长,原本能工作的部分也会被一起改坏。 在这里插入图片描述

更稳的迭代方式,是建立固定评审流程。

1. 固定四个检查机位

每一版都从相同的四个位置截图:

  • 主视角:判断第一印象与视觉焦点;
  • 俯视角:检查布局、密度和重复感;
  • 近景:检查材质、比例与穿插;
  • 低机位:检查天际线、灯光和雾的层次。

视角固定后,修改是否有效会更容易判断。

2. 把“好不好看”拆成可回答的问题

不要只问“画面是不是高级”,而要问:

  • 第一眼最先看到什么,它是否是主角?
  • 前景有没有提供尺度参照?
  • 中景是否拥挤,轮廓有没有粘在一起?
  • 远景是否被雾正确压低?
  • 主光方向是否统一?
  • 暖色灯是否真的在引导视线?
  • 材质之间是否有粗糙度差异?
  • 雨是在增加氛围,还是只在遮挡画面?

这些问题可以让 ChatGPT 给出更具体的建议,也让你自己更容易做判断。

3. 一轮只处理一个层级

推荐顺序是:

构图 → 尺度 → 明暗 → 色彩 → 材质 → 动效 → 细节

构图还没定,就开始雕刻集装箱上的锈迹,通常没有意义。镜头一改,那些细节可能根本看不见。

4. 记录性能预算

文件小,不代表运行一定流畅。场景中每增加一盏投射阴影的灯、一个透明层或一组独立网格,都可能增加成本。

可以先设一组朴素的预算:

项目建议起点说明
像素比不高于 1.5~1.75高分屏全分辨率很容易拖慢渲染
阴影灯1 个主灯其余灯尽量不投射阴影
雨点2000~6000根据设备动态调整
独立材质尽量复用材质切换会增加成本
重复物体优先实例化集装箱、窗户、路灯尤其适合
每帧逻辑只更新会动的内容静态对象不要重复计算

当场景对象很多时,可把重复集装箱改成 InstancedMesh。同一份几何和材质只提交一次,再通过矩阵决定每个实例的位置、旋转和缩放。它通常比创建几百个独立 Mesh 更合适。

5. 做降级,而不是只做一个“满配版”

启动时可以检测设备能力或测一小段帧率:

  • 性能充足:开启阴影、较多雨点和较高像素比;
  • 一般设备:减少雨点、降低阴影尺寸;
  • 较弱设备:关闭实时阴影,用烘焙色块和雾保留氛围。

好的轻量网页,不是让所有电脑硬跑同一套效果,而是让不同设备都能看到合理的版本。


九、从“会动的 Demo”走向真正可用的作品

做完一个雨夜港口之后,真正有价值的不是保存这一个页面,而是把它变成下一次还能复用的能力。 在这里插入图片描述

你可以逐步沉淀四类模块。

场景模块

统一管理背景色、雾、环境光、色调映射和窗口缩放。以后做雪山、机房或水下世界,都从同一套基础设施开始。

资产工厂

把 createContainer()、createBuilding()、createBridge() 这类函数整理成可配置工厂。输入尺寸、颜色和层数,返回一个完整组件。

效果系统

雨、雪、灰尘、萤火、波纹与光带都应该有独立的创建、更新和销毁方法。切换场景时,旧系统能被干净移除。

配置协议

把可变化的内容收口成 JSON:

{
  "weather": "rain",
  "fogDensity": 0.018,
  "containerRows": 5,
  "containerColumns": 6,
  "palette": ["#244d5a", "#6a3e2d", "#304b38"],
  "camera": [34, 22, 42]
}

这样一来,ChatGPT 可以帮助生成配置,RelayRouter 可以承载程序化调用,而你的 Three.js 代码只负责验证配置并渲染。职责清晰后,同一个引擎就能快速变出不同主题。

这类能力也不只适合游戏。它可以用于:

  • 把产品结构做成可旋转的解释页;
  • 把抽象数据变成可探索的空间;
  • 为博物馆、城市与建筑项目制作互动叙事;
  • 做物理、天文、地理和工程教学实验;
  • 制作活动页面里的轻量互动环节;
  • 在正式开发前快速验证镜头、玩法与视觉方向。

当然,它也有明确边界。浏览器 3D 不是大型游戏引擎的替代品。复杂骨骼动画、大规模物理、重度多人联机、超高精度资产管理,都需要更成熟的生产管线。选择 Three.js,不是因为它能包办所有事情,而是因为它让“打开一个链接就进入实时三维空间”这件事变得非常直接。

这也是为什么单文件 HTML 会重新吸引人:它让作品变得容易发送、容易打开、容易修改。代码不是压在作品背后的黑箱,而是作品本身的一部分。


十、最后:真正变小的,不只是文件

回到最开始那张图。 在这里插入图片描述

它让人惊讶的地方,不只是一个网页能画出雨、光、金属与雾,而是创作路径发生了变化。过去,一个人脑海里即使有完整场景,也可能卡在建模、材质、渲染、编程和工具链之间。现在,浏览器提供实时画布,Three.js 把图形接口变得可读,ChatGPT 帮助拆解需求与修正代码,RelayRouter 让成熟的交互流程能够被接进自己的程序。

这并不意味着创作从此不需要门槛。相反,当“做出来”变得更容易,真正拉开差距的会是判断:你想表达什么,画面为什么这样构图,哪些细节值得保留,哪些功能应该删掉,性能预算花在哪里,用户打开页面后的前十秒应该看到什么。

工具可以生成一座城,但它不会替你决定这座城为什么存在。

如果你准备动手,最合适的起点不是复制一个庞大的成品,而是先做一个很小的场景:一块地面、一盏灯、一排建筑、一组雨点和一个可以移动的镜头。让它先稳定运行,再逐轮增加结构、氛围与互动。

当你最终把它打包成一个 HTML 文件时,里面装着的并不是一座已经凝固的城市。

它装着的是一组等待浏览器执行的规则,一套属于你的视觉选择,以及一个每次打开都会重新发生的世界。


可直接复制的完整创作提示词

如果希望用 ChatGPT 帮你规划自己的 Three.js 场景,可以从下面这份提示词开始:

请帮我制作一个单页面 Three.js 互动场景。

场景主题:填写你想表现的地点、时间、天气和核心主体。
例如:雨夜港口,集装箱形成纵深通道,远处有门式吊机,湿润地面反射暖色工作灯,背景有薄雾和缓慢移动的云层。

技术要求:
1. 不引用外部图片、三维资产和音频,几何、纹理、粒子与简单声音尽量由代码生成;
2. 支持鼠标拖动旋转、滚轮缩放,并限制合理的镜头范围;
3. 优先保证普通笔记本运行稳定,限制像素比、阴影灯数量和粒子数量;
4. 使用雾、冷暖灯光、材质粗糙度和前中后景建立氛围,不靠堆叠物体;
5. 把地面、主体建筑、重复物体、灯光、天气、控制器和动画循环拆成独立函数;
6. 第一轮只交付可运行骨架,第二轮再增加画面细节;
7. 每次修改只给最小补丁,不要无关重写;
8. 代码中写清楚关键参数的作用和性能代价;
9. 如果使用 CDN,说明怎样在交付阶段打包成可离线打开的单个 HTML;
10. 输出前检查:黑屏风险、窗口缩放、资源释放、移动端像素比与控制台错误。

请先不要直接输出完整代码。先给我:
A. 场景对象清单;
B. 组件结构;
C. 性能预算;
D. 三轮开发计划;
E. 第一轮最小可运行版本。

当第一版能运行后,再使用下面的评审提示词:

下面是同一场景四个固定机位的截图,以及浏览器控制台和性能信息。

请以技术美术审查的方式工作:
1. 按严重程度列出构图、尺度、明暗、色彩、材质、雾和动效问题;
2. 区分“视觉问题”“代码问题”“性能问题”;
3. 本轮只选最值得修的 3 项;
4. 为每项给出可验证的修改目标;
5. 只提供最小代码补丁,并标注要修改的函数;
6. 不增加外部图片和三维资产;
7. 不执行大范围重构,保留现有组件接口;
8. 修改后告诉我应该从哪些机位复测、观察什么结果。

文章到这里,原理、代码和接入方式已经形成一条完整路径。剩下的部分,只能由你真正打开编辑器、保存第一个 HTML、在浏览器里看见第一个立方体时完成。

接口核对说明:本文示例使用 https://api.relayrouter.app/v1/chat/completions。正式发布或上线前,请以 RelayRouter 控制台当时展示的可用调用标识、账户规则与接口说明为准。

资料核对:RelayRouter 官网;API 地址迁移提示。官网用于核对兼容接口的公开说明,迁移页显示 API 调用域名保持不变。 在这里插入图片描述