3D与性能

数值 / 代码

首屏    只多一个经典脚本 effects.js（判定与调度，几KB），首屏里 three / gsap 都是0字节
时机    首屏画完 → 第一次滚动（滚轮、触摸、PageDown / 空格 / 方向键）→ requestIdleCallback（兜底1.2秒）→ 下载
不够格  减弱动效 / 省流量 / 两段都拿不到 WebGL → 一个字节都不下，留在静态版
叠加    海报上盖一层3D画布；海报不 display:none、不摘出 DOM（读屏照读 alt）
        3D 关着时槽位 display:none，降级的终点 = 今天的界面
调用    业务只调空操作入口（plan 的 fxFlipIn / fxSlip / fxNudge）：3D 没加载时什么都不做，
        业务代码里没有「3D 开没开」的分支；动画没播完就点下一题，直接跳到终点、不排队

用在哪

刷刷三处纸闪卡（首页牌堆、做题小牌堆、结算落堆）、岗岗案头手册、plan台历、小屋工具页展品与走进小屋、随笔球、漂浮层。刷刷另有一条「槽位只在3D能成时撑开」：本机成功过（记号shua-fx-ok）首帧就撑开、3D到了直接淡入；从没成功过就等就绪再撑开（0.3秒过渡），每台设备只跳这一次。小屋工具页更严：物件准备好了也要等它那一层看不见时才接管。

为什么

3D在这几个站里不承载信息：刷刷答题、岗岗查业务、plan排期都是一步不多、一毫秒不等。降级的终点就是今天那一页，关掉3D不用另做一套界面；读屏、键盘、SEO走的一直是静态那一层。

数值 / 代码

const strict = { alpha: false, antialias: true, depth: true, stencil: false, premultipliedAlpha: true,
                 preserveDrawingBuffer: false, powerPreference: "default", failIfMajorPerformanceCaveat: true };
const loose  = { ...strict, antialias: false, failIfMajorPerformanceCaveat: false };

严 WebGL2 → 宽 WebGL2 → （都不成）宽 WebGL1只探一次、记进诊断、立刻 loseContext()
每一段一块新画布；拿到的那个上下文直接交给渲染器，不另建
拿到严那段  → 按内存、核数起步（≤4 → 均衡，其余 → 高）
只拿到宽那段 → 一律 soft，不看内存、核数、指针、会话记账
两段都拿不到 → 静态：零请求、控制台零输出

用在哪

刷刷effects.js（3.11.2起）、岗岗desk-book.js、小屋四个岛（各岛quality.ts的probeWebGL()，漂浮层在hall-float.tsx里自己一份）、card查看器（2026-10-08跟上，acquireContext()：严参数被拒、或渲染器名是软件渲染，就关抗锯齿走省力档）。plan的台历2026-10-09跟上（93f8d72，fx3d/capability.ts的probeWebGL()）：严参数先要，被拒就放宽、关抗锯齿走软件档；渲染器名是SwiftShader、WARP这类的也归软件档；两段都拿不到才回静态。本站外壳的背景模糊「自动」档也靠这个标志判有没有显卡：只探一段WebGL1严参数，拿不到就按没显卡，模糊落lite（只压暗不模糊）；结果连UA存star-gpu，没测过先按lite。

为什么

一刀切拒绝软件渲染，屋主那台没显卡的台式机（Windows走WARP）就永远只看静态版。只放宽一条、其余参数照旧，有显卡的机器第一段就拿到，行为一字不变。判出软件渲染就钉soft、不看内存核数：那台机器32G、20核，按内存核数会判成高档，软件渲染跑高档就是灾难。

数值 / 代码

              刷刷 · 岗岗                         小屋（四个岛）
像素比        ≤1（高1.75 / 均衡1.25）              min(dpr, 1.5) 与面积上限取小
绘制缓冲      物理长边 ≤640，CSS 尺寸不变          展品80万 · 走动60万 / 停稳325万 · 随笔球100万 · 漂浮层60万
帧率          限30，按到期时刻跳帧                 同左（四处共用lib/frame-pacer.ts，2026-10-09起；原来按间隔，29ms）
抗锯齿        关                                    关（无 MSAA）
指针 / 滚动   不跟指针、不随滚动                    —
画质          同均衡档，不另砍                      关纸纹、各向异性1、几何同均衡
判档          只看这一次探测：拿到宽松那段就是 soft，排在会话记账、内存、核数之前
手机          —                                     随笔球手机版面 min(dpr, 2) 与130万取小，什么都不砍

用在哪

刷刷3.11.2起三档；岗岗同日；小屋四个岛2026-09-23跟进；card查看器2026-10-08跟进，它的省力档只关抗锯齿、像素比不压（画不许为性能牺牲：2040×1019@1.25下关抗锯齿帧耗时约40→19ms，再压像素比只多省4ms却发糊）。plan的台历2026-10-09跟上（93f8d72）：软件档像素比1、关纸纹、几何细分减半。

为什么

在屋主视口（2040×1019@1.25，SwiftShader）逐项开关投影、双面两遍、张数减半、纸纹、分辨率、抗锯齿，出帧都在9–13帧之间晃，差别在噪声里；把全站backdrop-filter和光晕的filter去掉，精简3D立刻稳定30帧、页面100帧。砍画质换不来帧率，所以只砍像素和帧。小屋把像素比从钉1改成min(dpr, 1.5)：屋主那台DPR 1.25，钉1只画64%的像素，他看得见糊、看不见少了几片叶子，像素预算先给分辨率。手机的2和精简的1.5别统一成一个数：一个封软件光栅器的CPU填充率，一个封高密度屏的绝对像素数——1.5在3.5的屏上只剩18%的像素，卡片标题当场糊。

数值 / 代码

const cappedTargetFps = { soft: 30 };                // 限了帧的档才有常数
const degradeBelow = { capped: 0.6, free: 0.55 };
const refreshFpsRange = [30, 120];
const watchWindowMs = 3_000;                         // 攒够3秒活跃时长判一次
const pauseMs = 200;                                 // 走进小屋：相邻两帧隔200ms以上算中间停过，不计入
                                                     // 工具页、随笔球：这一拍没画就断开
// 判一次
const delivered = (activeFrames * 1000) / activeMs;                   // 送出率
const fastestMs = sorted[Math.floor(sorted.length * 0.05)] || 16.7;   // 第5百分位
const screenFps = Math.min(120, Math.max(30, 1000 / fastestMs));      // 估这块屏
const target = capped ?? screenFps;
const ratio = capped ? degradeBelow.capped : degradeBelow.free;
if (delivered < target * ratio) 降一档;           // 高 → 均衡 → 静态；soft 扛不住直接记静态

用在哪

小屋三个three岛（工具页展品、走进小屋、随笔球）同一套判据，只有「中间停过」那段怎么断开两种写法（见代码注释）；随笔球手机版面目标固定30、拖动那一段不进窗口。刷刷：窗口是最近40个帧间隔，同样0.6／0.55，另加「出帧≥50帧一律不算慢」，soft要连续两个慢窗口才关，关了本会话记住。岗岗：「自身绘制耗时中位数」与「整页帧间隔均值」同时超标、累计2秒动画时间才卸载，soft的两条线按承诺帧率写（66.7ms、33.3ms）。漂浮层至今没有看门狗。

为什么

旧写法「N秒中位帧间隔＞X毫秒」两头都错：限30帧后间隔只有33.3／50／66.7三个值，中位数在一半一半处整体翻面，旧阈值又正好是50——同一构建三次量到47.7／49.7／59.6ms，活不活得下来靠抛硬币；每隔几帧卡120ms的页面真实只有22帧，中位数照样报正常；干净的30Hz屏上30.1帧反被判慢。三条规矩缺一不可：相对阈值；量平均送出率；不限帧的档目标从这块屏估，不写死60。做对了之后capped那类分支整个消失，一张表管所有档。

数值 / 代码

// 刷刷 effects-3d.js、岗岗 desk-book.js、小屋 lib/frame-pacer.ts 是同一个式子
const FRAME_INTERVAL_SLACK_MS = 4;
if (soft && SOFT.frameIntervalMs > 0) {
  const now = performance.now();
  if (nextDrawAt && now < nextDrawAt - FRAME_INTERVAL_SLACK_MS) return;   // 还没到：这一拍不画，ticker 不摘
  nextDrawAt = nextDrawAt && now - nextDrawAt < SOFT.frameIntervalMs
    ? nextDrawAt + SOFT.frameIntervalMs      // 落后不到一个间隔：接着排
    : now + SOFT.frameIntervalMs;            // 落后超过：从当下重排，不累积欠账
}

用在哪

刷刷、岗岗的soft档；小屋2026-10-09跟上：工具页展品、走进小屋、随笔球三个岛和门厅漂浮层共用一份lib/frame-pacer.ts（精简档和随笔球手机版面那道30帧闸门都是它），同一个式子、容差4ms。改前小屋是按间隔排（now - drawnAt < softFrameMs，29ms＝33.3留4ms）：rAF满60拍时同样是30帧，不满60拍时掉到每两拍一帧（45拍时约22帧，上面第一行）；改后45拍、40拍都回到30帧。

为什么

软件合成下rAF本来就常常不满60拍，按「离上一帧多久」排会被凑成每两拍画一次（约23帧）；按到期时刻排，长期平均仍是30帧。真正让固定4ms容差够用的是「落后超过一个间隔就重新基准」这一句：欠账一旦累积，卡顿之后就会连画补帧或持续跳帧。

数值 / 代码

// 本站总览的条目星球（assets/pages/index.js，回调名 globeFrame，量具按名字数）
function running() {
  return visible && !document.hidden && !kitOpen()               // 三道闸
      && (spin > 0 || vel !== 0 || !!target || !stopped());        // 还有东西在动
}
function globeFrame(now) {
  raf = 0;
  …算这一帧，只写 transform…
  if (running()) raf = requestAnimationFrame(globeFrame);       // 不要就退出：静止零帧
}
function kick() { if (!raf && visible && !document.hidden && !kitOpen()) raf = requestAnimationFrame(globeFrame); }
// IntersectionObserver 改 visible 后 kick()；visibilitychange 后 kick()

用在哪

刷刷：全站一个WebGL上下文、一块画布在三个槽位间移动，只在动画或指针阻尼进行中出帧，标签页隐藏时停。岗岗手册静止时不跑任何帧。plan只有补间在跑时才渲染。小屋工具页展品只在进度在变、主题在过渡、刚改尺寸或刚接管时画；随笔球离开视口或标签页隐藏就停。本站总览开头的条目星球照这套写：只在星球看得见、页面可见、没有整页弹层开着时跑rAF。

为什么

3D是点缀，静止时不该花任何电和帧。按需渲染也是看门狗判得对的前提：只统计动画进行中的帧，静止那段不进窗口，否则「没画」会被当成「画得慢」。

数值 / 代码

// 唯一入口：小屋 tool-3d.tsx 里那一行，逐字
const loadScene = import.meta.env.SSR ? null : () => import("./scene");

// scene/ 里逐符号（全仓只有 scene/ 能 import three 与 gsap）
import { WebGLRenderer, PerspectiveCamera, Mesh /* … */ } from "three";   // 禁止 import * as THREE

// vite.config.ts：压缩时保留许可注释
build.rolldownOptions.output.comments = { legal: true, annotation: false, jsdoc: false };

用在哪

小屋三个three岛。刷刷用esbuild把场景和两个vendor子集打成经典脚本IIFE（file://下也能注入）：three子集17个符号547KB（gzip 140KB），整包是742KB；GSAP只取核心；许可注释原样保留，另加来源说明与NOTICE。岗岗three子集13个导出符号、GSAP用官方UMD，两份许可注释原样保留。plan构建门禁：首屏入口chunk不得含three／gsap特征串，3D chunk必须含两份许可注释、不超过200KB gzip。

为什么

「不执行」不等于「不打包」：写在useEffect里、用next/dynamic的ssr: false，打包器照样给服务端再产一份three和gsap。经变量中转（先const env = import.meta.env再env.SSR），Vite的文本替换认不出来。整包比按需多约48KB。GSAP 3.13起全部免费，但许可证禁止删版权注释，而压缩默认会删。

数值 / 代码

刷刷   纸闪卡：首页牌堆（≥1180）、做题小牌堆、结算落堆      three 子集 + GSAP 核心，经典脚本 bundle
岗岗   案头手册：宽屏（>1120）右栏末尾一本摊开的书       three 子集 + GSAP UMD
plan   纸台历：侧栏空白处；甘特板落位；纸条飞进台历           three + GSAP，一个模块 import
card   画廊 Cover Flow：纯 CSS 3D，不靠 WebGL；查看器：three   importmap + ES module
小屋   工具页展品（three + GSAP，唯一用 ScrollTrigger）、走进小屋、随笔球；
       画内景深与漂浮层是手写 WebGL（约3.4KB / 岛约1.3KB gzip）
三档   有显卡 → 完整档（高 / 均衡）；只有软件渲染 → 精简档；拿不到 WebGL → 静态

用在哪

开新网站要加3D时先看这张表：落点放在本来就空着的地方（岗岗右栏末尾、plan侧栏空白、刷刷题数旁的小槽），物件照左边图标做成有厚度的同一个东西。手机上要不要3D按值不值算：小屋随笔球做了手机版面；岗岗手机3D屋主嫌代价大，一句话砍掉。

为什么

同一个屋主、同一台没显卡的台式机：哪一处在那台机器上是什么样子，得一眼查得到，否则「这台看不到3D」要逐个项目翻代码。差异也要写明：plan「只有软件渲染就不出」原来是有意没跟、留着待定，控制室10-08定照岗岗那套四家样板走，2026-10-09跟上（93f8d72）：严参数先要、被拒走软件档、两段都拿不到才回静态。card查看器原来不带failIfMajorPerformanceCaveat、软件渲染下照跑完整的three，2026-10-08改成两段，省力档只关抗锯齿、像素比不压。

数值 / 代码

色板    纸面 #FFFDFA / #F6F5F1 · 纸边 #E4E0D6 · 墨 #3E3C35 · 冷影海湾蓝 #6E8A93
光      漫反射量化成两三档平涂，没有镜面高光、没有反射
冷影    背光面掺一点海湾蓝（同门厅垂柳「后层掺海湾蓝」）
纸纹    着色器里程序化纸纤维，亮度 ±3%，不新增贴图
颜料边  每个面靠边深一圈（同「洇一层纸」转场外缘那圈）
投影    物件下一块柔边椭圆 rgba(74,77,53,.22)，运行时画，不开实时阴影
入夜    跟墙壁开关与系统深色，整体压暗偏冷（程序化的纸 .30 / .33 / .45）

用在哪

小屋工具页四件物件（paper.ts）；刷刷纸闪卡照搬这一套（纸色v3.11.0起对齐界面上的半透明白卡）；岗岗案头手册（颜色全走--book-*令牌，读不到就不画）；plan台历（现状：侧栏改深色后，2026-09-22由假投影改成three阴影贴图的真投影）。card的镭射是全场唯一「亮」的东西：一条随倾角滑过卡面的软带，只加不乘，加完照样压平涂、纸纹、颜料边。

为什么

物件和门厅那幅水彩画、洇纸转场说同一种话：它们是纸做的文具，不是产品渲染图。card的卡身是唯一的例外色（深蓝哑光#182B3D），因为全息闪卡本来就不是纸做的，拿纸色去涂只会得到一张「纸卡」；这两支色只归card用。

数值 / 代码

// 片元着色器（本页演示的写法）：每件物件一个 uFade（= 这一层的 present）
float bayer2(vec2 a) { a = floor(a); return fract(a.x * .5 + a.y * a.y * .75); }
float bayer4(vec2 a) { return bayer2(.5 * a) * .25 + bayer2(a); }    // 4×4，0..15/16
float th = bayer4(gl_FragCoord.xy) + 1. / 32.;
if (uFadeFlip > .5) th = 1. - th;     // 相邻两件阈值互补（按层的单双）
if (uFade < th) discard;              // uFade = 1：一个都不丢，停留姿态逐像素不变
// 投影本来就是半透明的一层：alpha 直接乘 uFade；深度测试照常

用在哪

小屋工具页：四件物件挂在同一块sticky舞台的画布上，相邻两件交接时同时看得见，各用自己的相机取景、后一层画在前一层上面。

为什么

不用半透明混合，就不用给翻动的纸页排序，深度测试照常；停留时uFade＝1，画面和不抖动时逐像素相同。要真透明得给两件各开一块离屏缓冲再合成，多两块画布大小的显存（1440×900、像素比1.75时带4倍多重采样约110MB，不带约25MB但交接时边缘有锯齿）。屋主2026-09-20看过实机后裁定：抖动就这样，不做离屏合成。

数值 / 代码

海报    尺寸960×640（3:2），透明底 WebP，每张 ≤40KB；.poster 带 aspect-ratio: 3 / 2，图没到也按3:2占位
截法    scripts/render-tool-posters.mjs：Node 自带 WebSocket 走 Chrome 调试协议，打开本机生产预览，
        滚到停留姿态，轮询 --rail-progress 直到停住并核对等于目标（不相等就报错、不写图），
        按 .visual 的矩形截图，sharp 转 WebP；生产代码里不为它留任何开关或调试路由
重截    改了造型、着色、时间线或停留姿态都要重截；--only shua / gang / card 只重截一张
实测    视口1440×900、2倍像素比、同一块991×660设备像素：通道差 >8的像素0.89%、最大差53、平均0.60
        （换图前截在进度0.6的那张：5.01%、最大差228）

用在哪

小屋工具页刷刷、岗岗、card三张海报；减弱动效、窄屏、低端机看到的就是它，取代了原来的虚线占位块。

为什么

3D是叠加层，静态版自己就得是完整的一页。最后一件不退场，访客先滚过去再回来时停的就是海报，所以海报必须等于终态。海报是截出来的、不是画的：造型和着色只有一份，换了画面重跑脚本就行。

数值 / 代码

// Ysevan_web/components/hall-walk/quality.ts
export const softMaxPixels  =   600_000;   // 走动：画被放大到远超源图，多画的像素买不到细节
export const softRestPixels = 3_250_000;   // 停稳：(2040×1.25)×(1019×1.25) = 3,248,062.5，向上取整
// 岛：循环要停的那一刻（heading === 0 && !wants）排下一帧调 scene.resize(restDensity, true)
//     改密度、改尺寸、重画在同一个同步任务里做完，合成器看不到中间状态（不闪）
//     重新起步时 kick() 先 resize(density, false) 换回走动那一档；这一帧清 lastRenderAt，不进看门狗

用在哪

小屋走进小屋的精简档（屋主那台没显卡的台式机走的就是它）。

为什么

墙角每幅画在屏幕上只有465 CSS宽，比源图636还小；走动预算只给它画250个像素，而门厅第一屏那张<img>都有396——走进去之后比走进去之前更糊，同一页里就有对照组。墙角完全静止，rAF当场退出，所以停稳重画是一次性开销（2026-09-24实测约18ms，readPixels强制同步量）；走动中一直保持ratio 1.0是98.6ms一帧，补不回来。验收判据因此换成「走进去之后那幅画的清晰度不得低于门厅第一屏里同一幅画」。