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:
{
"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:
<!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:
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:
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 放入阻断条件,但仍输出它以帮助观察极端卡顿;严格项目可以再加入独立预算。
运行、验证与处理失败
在项目目录先安装依赖及浏览器,再记录健康版本的基线:
npm install
npx playwright install chromium
npm run baseline预期结果:生成 package-lock.json、dist/ 和 perf-baseline.json,统计对象列出浏览器版本及三类分位数,控制台最后一行是:
BASELINE_SAVED审核基线后将 package-lock.json 和 perf-baseline.json 提交到仓库。在相同测试机器和浏览器模式上,对新提交运行:
npm ci
npm run perf预期结果:符合阈值时最后一行类似以下内容,进程退出码为 0;具体毫秒数、Chromium 版本和绘制数量会随实际环境变化:
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 计时手段定位。不要用一次偶发失败直接更新基线:先核对环境、重复采样,再根据相同轨迹上的指标变化确认问题。