Kage： 一个 244KB 文件，做出百万级视觉效果

Github:github.com/MengTo/kage

痛点：为什么大多数 3D 网页体验都不够"沉浸"？

你可能见过很多 Three.js 演示——场景切换像幻灯片，光影效果千篇一律，加载慢得让人想关页面。更糟糕的是，这些项目往往需要一堆构建工具和依赖链，改一行代码都要重新打包。到了移动端，体验更是灾难性的，PC 上流畅的动画在手机上直接卡成 PPT。

Kage 用一种"极简主义"的方式解决了所有这些问题：一个文件、一个场景、一条连续的镜头路径。

核心功能一览

技术架构：极简背后的精妙

1. 单文件哲学

Kage 最让人惊讶的设计决策是：所有内容都在一个 index.html 文件里。

kage/
├── index.html          <span># 主文件，244KB</span>
├── PROMPT.md           <span># 构建提示（如何复现这个项目）</span>
├── README.md
├── assets/
│   └── kage-preview.webp
└── secret-pathways-assets/
    ├── fonts.css       <span># 字体样式</span>
    ├── foreground/     <span># 前景元素</span>
    ├── generated/      <span># 生成式图像</span>
    └── three.<span>min</span>.js    <span># Three.js r149 打包版</span>

这不是偷懒，而是刻意的设计选择。README 里说得很清楚："Kage is a deliberately small static site." 为什么要这样做？因为零依赖意味着不需要 npm install，不需要 webpack 配置；单文件意味着下载后本地起个服务器就能跑，分享方式几乎无限；没有运行时网络请求意味着性能完全可控，不会有意外的阻塞。

2. 程序化场景构建

这是 Kage 最核心的技术亮点。传统 Three.js 项目需要在 Blender 里建模、导出为 GLTF 格式、再在 Three.js 里加载渲染。Kage 完全跳过了前两步——所有 3D 元素都是用代码生成的。

<span>// 概念示意：程序化生成鸟居</span>
<span>function</span> <span>createTorii</span>(<span>x, y, z</span>) {
  <span>const</span> geometry = <span>new</span> <span>THREE</span>.<span>BoxGeometry</span>(<span>0.3</span>, <span>2</span>, <span>0.3</span>);
  <span>const</span> material = <span>new</span> <span>THREE</span>.<span>MeshStandardMaterial</span>({ 
    <span>color</span>: <span>0xCC3300</span>,  <span>// 朱红色</span>
    <span>emissive</span>: <span>0x331100</span>  <span>// 微弱发光</span>
  });
  <span>// 两根立柱 + 两根横梁 = 鸟居</span>
  <span>// ...（实际代码更复杂）</span>
}

PROMPT.md 里详细描述了每个元素的构建方式：鸟居、石阶、纸灯笼、月亮、地形、树木、雾气、雨、落叶、余烬——全部用 THREE.BoxGeometry、THREE.PlaneGeometry 等基础几何体组合而成。

这种做法的好处是：没有几百MB的3D模型文件，浏览器直接解析代码就能加载；改代码就能改场景，不需要重新导出模型；任何支持 WebGL 的浏览器都能跑，跨平台无障碍。

3. 滚动驱动的连续镜头

传统网页的章节切换是"跳转"，Kage 的章节切换是"移动"。

想象一下你坐在一辆缓慢行驶的缆车上，随着页面滚动，镜头平滑地从一个场景移动到下一个场景。这不是幻灯片切换，而是一条连续的摄像机路径：

<span>章节1: 鸟居入口 → 石阶 → </span>
<span>章节2: 蜡烛照亮的小径 → </span>
<span>章节3: 石灯笼、树木 → </span>
<span>章节4: 山顶神社 → </span>
<span>章节5: 朱红色大月亮</span>

每个章节都像电影里的一个"分镜"，有独立的构图、光线和氛围。这种设计让整个体验像在看一部慢节奏的艺术电影。

4. 电影级后期处理

Kage 的视觉效果远超普通的 Three.js 演示，秘诀在于精心调校的后期处理管线。在光影层面，Bloom（泛光）让灯光和月亮产生柔和的光晕，Film Grain（胶片颗粒）模拟老电影的质感，Vignette（暗角）让画面边缘渐暗以聚焦中心。在空间层面，Depth Haze（深度雾化）让远处的物体变模糊，增强纵深感。在色彩层面，暖色灯笼光与冷色月光形成强烈的冷暖对比，而那轮巨大的朱红色月亮则为整个画面注入了超现实的氛围。

这些效果组合在一起，让画面看起来像用电影镜头拍摄的，而不是电脑渲染的。

5. 生成式图像叠加

Kage 在 3D 场景之上，还叠加了 AI 生成的 2D 图像，创造出 2.5D 的视差效果。

这些前景元素（grass、maple branches、sakura、stones、walls、ruins、bushes、hills、pines、lanterns）以半透明方式叠加在 3D 场景底部，随章节切换而淡入淡出。这种混合技术让画面层次更丰富，同时保持了"数字艺术书"的感觉。

设计亮点

1. "PROMPT.md" 设计模式

Kage 附带了一个 PROMPT.md 文件，详细描述了如何复现这个项目。这不是普通的文档，而是一个可执行的设计蓝图：

"Create a single-page, cinematic WebGL experience called Kage: a five-chapter night walk through a fictional Kyoto mountain temple."

这种模式让其他开发者可以直接学习如何用代码构建 3D 场景、理解电影级视觉效果的实现方式，甚至复用这套方法论创作自己的项目。

2. 色彩系统

整个项目的色彩被严格控制在几个关键色：近黑的背景与阴影、蓝炭色的夜空与远景、暖琥珀色的灯光与火焰、骨白色的月光与雪、以及朱红色的鸟居与月亮。这种克制的色彩搭配让画面既有东方美学的含蓄，又有现代设计的高级感。

3. 无障碍设计

作为一个视觉艺术项目，Kage 依然注重可访问性：

• 语义化 HTML 标签
• 响应式移动端布局
• 减少动效模式（reduced-motion）
• 自定义光标仅限精细指针设备
• 每个章节的导航锚点

适用场景

局限性与挑战

1. 内容更新成本高

所有场景都写在 244KB 的 HTML 里，修改任何细节都需要编辑这个巨型文件。没有内容管理系统，没有热更新，改一行代码就要重新部署整个文件。

2. SEO 不友好

单文件 + WebGL 的组合对搜索引擎来说几乎不可见。如果你的项目需要被搜索到，这不是最佳选择。

3. 性能瓶颈

244KB 的 HTML 文件在解析时会阻塞主线程。在低端设备上，首次加载可能会有明显的白屏时间。

4. 维护复杂度

所有代码都在一个文件里，随着项目发展，维护成本会急剧上升。Kage 目前只有 5 个章节，但如果要扩展到 50 个章节，这个架构就撑不住了。

与类似项目的对比

Github:github.com/MengTo/kage

总结

Kage 证明了一件事：好的设计不需要复杂的工具链。

一个设计师用一个 HTML 文件、一个 Three.js 库、一段构建提示，就能创造出让人屏息的沉浸式体验。这不是技术炫技，而是对"极简主义"的极致追求。

如果你正在思考如何用 Web 技术讲述一个故事、展示一件作品、或者创造一种体验，Kage 给出了一个漂亮的答案：少即是多，单文件就是无限可能。

关注

如果这篇文章对你有启发，欢迎关注我，获取更多技术产品的深度分析和开源项目的创意拆解。