Web 图形与 3D / 系统课时

用脚本回放检测性能回归

用脚本回放检测性能回归

场景改动后,平均 FPS 可能没有明显变化,偶发卡顿和 Draw Call 增长却已经出现。这里把相机运动固定为逐帧轨迹,用 Playwright 回放生产构建,采集帧间隔分位数及 Three.js 绘制统计,并让超出阈值的构建自动失败。

学习目标

  • 固定浏览器、视口和相机轨迹,获得可重复对比的测试条件。
  • 计算帧间隔的 p50、p95、p99,以及绘制调用与三角形数量的 p95。
  • 保存受审核的基线,使用自动化退出码阻止性能回归。

固定测试条件与统计口径

示例采用 Node.js 20.19+、Three.js 0.181.0、Vite 7.1.0 和 Playwright 1.56.0。测试生产构建,而非带热更新的开发服务器。首次安装生成 package-lock.json,之后 CI 使用 npm ci;Playwright 安装与当前包版本对应的 Chromium。

本例固定 390×844 CSS 像素、DPR=1、Chromium 无头模式与同一测试机器。相机预热 120 帧、正式记录 360 帧,连续执行 3 轮;每轮先求分位数,再取 3 轮结果的中位数。360 个值排序后,p95 是第 342 个值,而不是平均帧时长。

记录的是相邻 requestAnimationFrame 回调时间戳之差,反映帧呈现节奏和卡顿,但不是 GPU 指令执行时间。renderer.info.render.calls 与 triangles 记录本次 WebGL 渲染的提交统计。示例每帧只有一次 renderer.render();若有多道后处理,先设置 renderer.info.autoReset = false,读完本帧所有道次的累计值后调用 renderer.info.reset()。

制作固定相机轨迹的场景

在空目录创建 package.json、index.html、main.js 和 perf.mjs。前端用 12×12 个立方体构造可见负载,并复用同一份几何体与材质。相机的角度只由采样帧编号决定,不由运行速度决定,因此慢设备不会跳过路径区段。

package.json:

json
{
  "name": "three-perf-replay",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "vite build",
    "baseline": "npm run build && node perf.mjs --baseline",
    "perf": "npm run build && node perf.mjs"
  },
  "dependencies": {
    "three": "0.181.0"
  },
  "devDependencies": {
    "vite": "7.1.0",
    "playwright": "1.56.0"
  }
}

该配置在每次采集前构建正式资源,baseline 负责首次记录,perf 用已保存的结果做比较。

index.html:

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Three.js 回放基准</title>
</head>
<body>
  <script type="module" src="/main.js"></script>
</body>
</html>

main.js:

js
import * as THREE from 'three';

const renderer = new THREE.WebGLRenderer({ antialias: false });
renderer.setPixelRatio(window.devicePixelRatio);
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.style.margin = '0';
document.body.appendChild(renderer.domElement);

const scene = new THREE.Scene();
scene.background = new THREE.Color(0x101820);
scene.add(new THREE.HemisphereLight(0xffffff, 0x444444, 2));
const camera = new THREE.PerspectiveCamera(
  55, window.innerWidth / window.innerHeight, 0.1, 100
);
const geometry = new THREE.BoxGeometry(0.8, 0.8, 0.8);
const material = new THREE.MeshStandardMaterial({ color: 0x26a69a });

for (let x = 0; x < 12; x++) {
  for (let z = 0; z < 12; z++) {
    const mesh = new THREE.Mesh(geometry, material);
    mesh.position.set(x - 5.5, 0, z - 5.5);
    scene.add(mesh);
  }
}

// 对自动化暴露一次性回放入口,不依赖真实经过的秒数。
window.runReplay = (warmup = 120, frames = 360) => new Promise(resolve => {
  const intervals = [], calls = [], triangles = [];
  let previous = null;
  let index = 0;

  function tick(timestamp) {
    const angle = 2 * Math.PI * (index % frames) / frames;
    camera.position.set(16 * Math.sin(angle), 9, 16 * Math.cos(angle));
    camera.lookAt(0, 0, 0);
    renderer.render(scene, camera);

    // 排除预热期;逐帧读取渲染完成后的绘制统计。
    if (index >= warmup) {
      intervals.push(timestamp - previous);
      calls.push(renderer.info.render.calls);
      triangles.push(renderer.info.render.triangles);
    }
    previous = timestamp;
    index++;
    if (index < warmup + frames) requestAnimationFrame(tick);
    else resolve({ intervals, calls, triangles });
  }
  requestAnimationFrame(tick);
});

预期效果:页面内出现立方体网格;启动回放后,相机每 360 帧环绕一周。场景没有随机数、网络资源或实时物理步进,方便排除非确定性输入。

自动采样并执行回归门禁

测试脚本用 Vite 的 preview() 启动生产构建,Playwright 设置移动视口,等待 runReplay 就绪,再运行三轮。分位数采用“向上取整的排序位置”,避免样本数量相同时统计方法不一致。将基线与 Chromium 版本一起保存,阈值取 p95 帧间隔相对基线上升不超过 15% 且不超过 33.3 ms,绘制调用和三角形 p95 各允许增长 10%。

固定轨迹回放与性能回归判定的数据流

perf.mjs:

js
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { chromium } from 'playwright';
import { preview } from 'vite';

// 最近秩分位数:p95 对 360 个样本取升序第 342 个。
const percentile = (values, p) =>
  [...values].sort((a, b) => a - b)[Math.ceil(values.length * p) - 1];
const median = values => percentile(values, 0.5);
let server;
let browser;

try {
  server = await preview({
    preview: { host: '127.0.0.1', port: 4173, strictPort: true }
  });
  browser = await chromium.launch({ headless: true });
  const context = await browser.newContext({
    viewport: { width: 390, height: 844 },
    deviceScaleFactor: 1,
    isMobile: true,
    hasTouch: true
  });
  const page = await context.newPage();
  await page.goto('http://127.0.0.1:4173/', { waitUntil: 'load' });
  await page.waitForFunction(() => typeof window.runReplay === 'function');

  const runs = [];
  for (let i = 0; i < 3; i++) {
    const data = await page.evaluate(() => window.runReplay(120, 360));
    runs.push({
      p50: percentile(data.intervals, 0.5),
      p95: percentile(data.intervals, 0.95),
      p99: percentile(data.intervals, 0.99),
      calls: percentile(data.calls, 0.95),
      triangles: percentile(data.triangles, 0.95)
    });
  }
  const value = name => median(runs.map(run => run[name]));
  const current = {
    scene: 'orbit-144-v1',
    chromium: browser.version(),
    p50FrameMs: value('p50'),
    p95FrameMs: value('p95'),
    p99FrameMs: value('p99'),
    p95Calls: value('calls'),
    p95Triangles: value('triangles')
  };
  console.log(JSON.stringify(current, null, 2));

  const baselinePath = 'perf-baseline.json';
  if (process.argv.includes('--baseline')) {
    writeFileSync(baselinePath, JSON.stringify(current, null, 2) + '\n');
    console.log('BASELINE_SAVED');
  } else {
    if (!existsSync(baselinePath)) throw new Error('先运行 npm run baseline');
    const base = JSON.parse(readFileSync(baselinePath, 'utf8'));
    if (base.scene !== current.scene || base.chromium !== current.chromium) {
      throw new Error('场景或 Chromium 版本不一致,请检查测试环境');
    }
    const checks = {
      frame: current.p95FrameMs <= Math.min(33.3, base.p95FrameMs * 1.15),
      calls: current.p95Calls <= Math.ceil(base.p95Calls * 1.1),
      triangles: current.p95Triangles <= Math.ceil(base.p95Triangles * 1.1)
    };
    const passed = Object.values(checks).every(Boolean);
    console.log(passed ? 'PASS' : 'FAIL', JSON.stringify(checks));
    if (!passed) process.exitCode = 1;
  }
} catch (error) {
  console.error('BENCH_ERROR:', error.message);
  process.exitCode = 2;
} finally {
  await browser?.close();
  if (server) {
    await new Promise(resolve => server.httpServer.close(resolve));
  }
}

代码中的 baseline 模式仅供首次校准或经过评审的性能预算变更使用。正常 CI 只能执行 perf,否则每次提交都重写基线,回归检测就失效。示例没有把 p99 放入阻断条件,但仍输出它以帮助观察极端卡顿;严格项目可以再加入独立预算。

运行、验证与处理失败

在项目目录先安装依赖及浏览器,再记录健康版本的基线:

bash
npm install
npx playwright install chromium
npm run baseline

预期结果:生成 package-lock.json、dist/ 和 perf-baseline.json,统计对象列出浏览器版本及三类分位数,控制台最后一行是:

text
BASELINE_SAVED

审核基线后将 package-lock.json 和 perf-baseline.json 提交到仓库。在相同测试机器和浏览器模式上,对新提交运行:

bash
npm ci
npm run perf

预期结果:符合阈值时最后一行类似以下内容,进程退出码为 0;具体毫秒数、Chromium 版本和绘制数量会随实际环境变化:

text
PASS {"frame":true,"calls":true,"triangles":true}

超限时输出 FAIL、各项真假值并以退出码 1 结束,适合 CI 拦截;预览端口被占用或 WebGL 无法初始化等执行错误则以退出码 2 结束。例如健康基线 p95=18 ms、Draw Call p95=120,则本规则允许的 p95 帧间隔上限为 20.7 ms,绘制调用上限为 132;若新版本实测 24 ms、122 次调用,应先检查着色器编译、纹理上传、GC 或片元负载,而不是直接认定绘制调用增加。

当 p95 和 Draw Call 同时上涨,优先检查新加的 Mesh、材质变体、视锥剔除与后处理道次;当只有帧间隔上涨,则补用浏览器 Performance 录制和 GPU 计时手段定位。不要用一次偶发失败直接更新基线:先核对环境、重复采样,再根据相同轨迹上的指标变化确认问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用脚本回放检测性能回归

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通