前端视觉回归报告：截图比对用例膨胀到两千张后怎么瘦身不漏检

前端迭代这两年越来越快，组件库换了两轮，断点从两个加到四个。伴随而来的是一件很具体的事：视觉回归的基线图，从最初的几十张攒到了两千多张。

现在每晚 CI 跑视觉回归要 40 分钟，第二天早上打开报告红灯 200 张。翻一遍，180 张是字体渲染差异、抗锯齿抖动、动画还没停下来就截了图；剩下 20 张里，真缺陷可能只有一两个。

于是团队形成了一个默契动作：全选，点 approve，更新基线。三个月后这套视觉回归还在跑、还在消耗 CI 时间，但已经抓不到任何东西了——因为基线每天都被无条件重写。

一、审计结论摘要

审计对象不是「视觉回归该不该做」，而是这 2000 多张基线图现在的资产质量。四条发现按风险排序。

第一，用例集从未被审计过：没有一张图能回答历史失败率多少、失败里有多少是假阳性、上一次真正抓到缺陷是什么时候。缺这三个数，删与留都只能靠感觉。

第二，假阳性只被容忍、没被分类。字体渲染、抗锯齿、动画未停、异步数据未就绪这四类的治理手段完全不同，混在一起就只能靠放宽容差，而容差一放宽，真缺陷也跟着漏。

第三，重复覆盖严重：同一组件在四个断点各存一张几乎相同的图，装饰性静态图占比不低，承载的缺陷信号接近于零。

第四，也是最危险的：更新基线没有门槛。任何人任何时候都能一键 approve，基线不再是「已知正确的样子」，而变成「昨天晚上的样子」。

建议动作：全量审计打标、按价值分层；假阳性按根因分别治理；重复与装饰图删除或降级为语义断言；基线更新收进 CODEOWNERS 与差异面积阈值双重门禁。第五节给配置，第六节给脚本，第七节给验收度量。

二、失控信号：视觉回归什么时候已经名存实亡

瘦身之前先确认是不是真的病了。四个信号，命中两个就该动手。

信号一，approve 变成肌肉记忆：评审失败时第一反应是「又是字体」，而不是先看差异图。信号二，红灯数量长期稳定在高位——健康状态应该是平时接近零、改样式那几天集中冒出来；如果不管改什么都固定红一两百张，说明红灯已与代码变更解耦。

信号三，基线提交历史里全是「update snapshots」且不关联任何缺陷单，基线更新没有可追溯性。信号四，CI 耗时开始挤占别的阶段，团队讨论「要不要只在夜间跑」——一旦退出提交前反馈环，价值会再降一档。四个信号指向同一件事：问题不在用例不够多，而在信噪比崩了，所以解法是把分母降下来、把假阳性治掉，而不是加机器加并发。

三、按价值分层：给每张基线图算一次账

审计口径要先定死，每张基线图算四个数，缺一个都判不准。

历史失败率＝失败次数／执行次数，衡量这张图有多吵；失败率高不等于没价值，但失败几乎全是假阳性时它就是纯噪声源。假阳性占比＝人工判定为假阳性的次数／失败次数，这是最关键、也最少被统计的一个数，它直接决定这张图该治理还是该删。

距最后一次抓到真缺陷的天数：视觉回归的价值不在跑了多少次，而在挡住过什么，两年没抓到过缺陷的图属于负资产。覆盖的组件与断点：同一组件在三个断点各存一张，往往只有一张真正承载响应式布局风险。

四个数算完，分层规则就很简单：抓到过真缺陷且假阳性可控的保留；红灯几乎全是假阳性的先按根因治理，治理不动就降级成语义断言，别再用像素守；从未抓到缺陷或长期无变化的删除；同组件同断点重复的只留信息量最大的一张。要强调一句：删除的依据是「没抓到过缺陷且不稳定」，不是「看起来不重要」。

四、假阳性根因分类：先把 180 张红灯拆开

假阳性不能用一个容差值解决。不同根因的物理来源不同，治理手段也不同；混在一起调 threshold，结果就是假阳性没治干净、真缺陷先漏了。下面这张表按 180 张假阳性拆分根因占比与处置手段。

这张表要抓住前两行：字体渲染与动画未停合计占近七成，而它们的治理都在环境与配置层，一次改完长期有效、与具体用例无关；调容差则是唯一一个既治不了根又会削弱检出能力的手段，应该排在最后。分类还有附带收益——它让 approve 变成有依据的判断，红灯重新变得可读，这是视觉回归恢复作用的前提。

【配图1】

五、配置层治理：threshold、animations、mask 与语义就绪

治理动作大部分落在配置里，而不是用例里。环境层先固定：CI 用同一份 Docker 镜像跑视觉回归，字体、字体版本、渲染库全部锁死，本地开发机不参与基线生成——仅此一项就能吃掉表里最大的一类假阳性。

比对参数分两层。threshold 管单像素颜色容差，用来吸收抗锯齿与次像素渲染差异，它不改变「多少像素算失败」；maxDiffPixelRatio 管整张图允许的差异面积占比，用来拦住真正的布局错位。两个一起用才有意义：只放前者，布局崩了照样报；只放后者，字体一抖就大面积超阈值。

动态区域用 mask 遮，不要靠调容差忍：倒计时、库存角标、头像这些天然会变的区域遮掉之后，剩下的部分反而更值得守。时机上用语义就绪替代等待时长——要等的是「数据渲染完了」这个事实（列表条数到了、字体加载完了、loading 消失了），而不是一个凭经验写的 waitForTimeout。

最后一件事与配置无关，但决定成败：把基线更新收进门禁。视觉回归失败必须由组件负责人评审，差异面积超过阈值时禁止一键 approve，基线更新提交必须关联变更说明或缺陷单。没有这道门，前面所有治理都会在三个月后被重新点废。

六、可运行实现：稳定性配置 + 审计脚本

第一段是 Playwright 配置，把上面的比对口径固化下来；csv reporter 是审计脚本的输入来源。

// playwright.config.js —— 视觉回归稳定性配置（@playwright/test）
// 运行：npx playwright test --project=visual-desktop
const { defineConfig, devices } = require('@playwright/test');

module.exports = defineConfig({
  testDir: './tests',
  timeout: 60_000,
  fullyParallel: true,
  workers: process.env.CI ? 4 : undefined,
  reporter: [
    ['list'],
    // 这份 csv 是审计脚本的输入：每张图每次跑的结果都要留痕
    ['csv', { outputFile: 'test-results/visual-history.csv' }],
    ['html', { outputFolder: 'playwright-report' }],
  ],
  expect: {
    toHaveScreenshot: {
      maxDiffPixelRatio: 0.002, // 允许 0.2% 面积差异：拦住布局错位，放过零星抖动
      threshold: 0.15,          // 单像素颜色容差：吸收抗锯齿与次像素字体渲染差异
      animations: 'disabled',   // 截图前把 CSS 动画与过渡置为结束态
      caret: 'hide',            // 隐藏文本光标
      scale: 'css',             // 固定按 CSS 像素缩放，避免高分屏基线互不兼容
      stylePath: './tests/visual-stabilize.css', // 注入稳定化样式：关过渡、固定字体平滑
      timeout: 10_000,
    },
  },
  use: {
    baseURL: process.env.BASE_URL || 'http://127.0.0.1:5173',
    trace: 'retain-on-failure',
    screenshot: 'only-on-failure',
    video: 'off',
  },
  projects: [
    { name: 'visual-desktop', use: { ...devices['Desktop Chrome'], viewport: { width: 1440, height: 900 } } },
    { name: 'visual-tablet', use: { ...devices['Desktop Chrome'], viewport: { width: 834, height: 1112 } } },
    { name: 'visual-mobile', use: { ...devices['Pixel 7'] } },
  ],
});

配置里 stylePath 引用的稳定化样式，缺它配置会报错：

/* tests/visual-stabilize.css —— 截图前注入，压掉渲染层的随机差异 */
*, *::before, *::after {
  transition: none !important;
  animation-duration: 0s !important;
  animation-delay: 0s !important;
  caret-color: transparent !important;
  -webkit-font-smoothing: antialiased;
  text-rendering: geometricPrecision;
}
img, video { background: #ffffff; }   /* 未加载完的媒体区域固定为白底 */

第二段是用例写法：一张高价值图怎么用 mask 与语义就绪把假阳性挡在截图之前，一张装饰图怎么降级成语义断言、彻底退出像素基线。

// tests/visual.spec.js —— 高价值图守像素，装饰图降级为语义断言
const { test, expect } = require('@playwright/test');

test('商品卡片：核心业务组件，多断点保留像素比对', async ({ page }) => {
  await page.goto('/shop/list?fixture=stable-20');

  // 等语义就绪，而不是等时长：数据条数到了、字体加载完了再截图
  await expect(page.getByRole('list', { name: '商品列表' })).toBeVisible();
  await expect(page.getByTestId('product-card')).toHaveCount(20);
  await page.evaluate(() => document.fonts.ready);

  await expect(page.getByTestId('product-card').first()).toHaveScreenshot(
    'product-card-default.png',
    {
      // 遮掉天然会变的区域：库存角标、倒计时、头像
      mask: [
        page.getByTestId('stock-badge'),
        page.getByTestId('countdown'),
        page.locator('.user-avatar'),
      ],
      maskColor: '#000000',
    }
  );
});

test('首页 hero：纯装饰图，降级为语义断言，不再进像素基线', async ({ page }) => {
  await page.goto('/');
  const hero = page.getByTestId('hero-banner');

  await expect(hero).toBeVisible();
  await expect(hero).toHaveAttribute('data-campaign', /^camp-\d{4}-\d{2}$/);
  await expect(hero.getByRole('link', { name: '立即参与' })).toHaveAttribute('href', /\/campaign\//);
  await expect(hero.getByRole('img')).toHaveAttribute('alt', /.+/);
  // 这里刻意不写 toHaveScreenshot：装饰图的像素变化不承载缺陷信号，只承载假阳性
});

第三段是审计脚本：读历史结果 CSV，按四个口径给每张图打标签、对同组件同断点的重复基线去重，最后输出假阳性集中度与真缺陷覆盖率。

"""
audit_visual_snapshots.py —— 视觉回归基线集瘦身审计

输入 CSV 列（可由团队的历史结果聚合而成）：
  snapshot      基线图文件名，如 product-card-default-1440.png
  component     所属组件
  breakpoint    断点：desktop / tablet / mobile
  runs          历史执行次数
  failures      历史红灯次数
  false_pos     其中被人工判定为假阳性的次数
  real_defects  其中真正抓到缺陷的次数
  last_defect   最后一次抓到真缺陷的日期 YYYY-MM-DD，没有则留空

用法：
  python audit_visual_snapshots.py visual-history.csv --today 2026-09-15 --out audit-result.csv
"""

import argparse
import csv
from collections import defaultdict
from datetime import date


def days_since(value, today):
    if not value:
        return None
    y, m, d = (int(x) for x in value.strip().split("-"))
    return (today - date(y, m, d)).days


def classify(row, today, fp_gate, stale_days):
    """返回 (标签, 失败率, 假阳性占比, 距上次真缺陷天数, 理由)"""
    runs = max(1, row["runs"])
    fail_rate = row["failures"] / runs
    fp_rate = (row["false_pos"] / row["failures"]) if row["failures"] else 0.0
    since = days_since(row["last_defect"], today)

    if row["real_defects"] > 0 and fp_rate < fp_gate:
        return "保留", fail_rate, fp_rate, since, "抓到过真缺陷且假阳性可控"
    if row["failures"] >= 5 and fp_rate >= fp_gate:
        return "降级", fail_rate, fp_rate, since, "假阳性占比过高：先按根因治理，治理不动改语义断言"
    if since is None or since > stale_days:
        return "删除", fail_rate, fp_rate, since, "从未抓到缺陷或长期无变化"
    return "保留", fail_rate, fp_rate, since, "失败率低，仍在观察窗口内"


def load_rows(path):
    rows = []
    with open(path, newline="", encoding="utf-8-sig") as f:
        for raw in csv.DictReader(f):
            rows.append({
                "snapshot": (raw.get("snapshot") or "").strip(),
                "component": (raw.get("component") or "").strip(),
                "breakpoint": (raw.get("breakpoint") or "").strip(),
                "runs": int(raw.get("runs") or 0),
                "failures": int(raw.get("failures") or 0),
                "false_pos": int(raw.get("false_pos") or 0),
                "real_defects": int(raw.get("real_defects") or 0),
                "last_defect": (raw.get("last_defect") or "").strip(),
            })
    return [r for r in rows if r["snapshot"]]


def dedupe(rows):
    """同组件同断点的重复基线：只保留信息量最大的一张。"""
    groups = defaultdict(list)
    for r in rows:
        groups[(r["component"], r["breakpoint"])].append(r)
    removed = 0
    for group in groups.values():
        keeps = [r for r in group if r["label"] == "保留"]
        if len(keeps) <= 1:
            continue
        best = max(keeps, key=lambda x: (x["real_defects"], x["failures"] - x["false_pos"], x["runs"]))
        for r in keeps:
            if r is not best:
                r["label"] = "删除"
                r["reason"] = "同组件同断点存在重复基线，保留信息量最大的一张"
                removed += 1
    return removed


def main():
    ap = argparse.ArgumentParser(description="视觉回归基线集瘦身审计")
    ap.add_argument("input", help="历史结果 CSV")
    ap.add_argument("--today", default=None, help="审计基准日 YYYY-MM-DD，默认系统当天")
    ap.add_argument("--fp-gate", type=float, default=0.6, help="假阳性占比阈值，超过即降级")
    ap.add_argument("--stale-days", type=int, default=180, help="多少天没抓到真缺陷算过期")
    ap.add_argument("--out", default="audit-result.csv")
    args = ap.parse_args()

    today = date.today()
    if args.today:
        y, m, d = (int(x) for x in args.today.split("-"))
        today = date(y, m, d)

    rows = load_rows(args.input)
    if not rows:
        raise SystemExit("CSV 中没有可用记录，请检查列名：snapshot/component/breakpoint/runs/failures/false_pos/real_defects/last_defect")

    for row in rows:
        label, fail_rate, fp_rate, since, reason = classify(row, today, args.fp_gate, args.stale_days)
        row.update({
            "label": label,
            "fail_rate": round(fail_rate, 4),
            "fp_rate": round(fp_rate, 4),
            "days_since_defect": since if since is not None else "",
            "reason": reason,
        })
    removed = dedupe(rows)

    fields = ["snapshot", "component", "breakpoint", "runs", "failures", "false_pos",
              "real_defects", "fail_rate", "fp_rate", "days_since_defect", "label", "reason"]
    order = {"保留": 0, "降级": 1, "删除": 2}
    rows.sort(key=lambda r: (order.get(r["label"], 9), -r["fp_rate"]))
    with open(args.out, "w", newline="", encoding="utf-8-sig") as f:
        writer = csv.DictWriter(f, fieldnames=fields, extrasaction="ignore")
        writer.writeheader()
        writer.writerows(rows)

    total = len(rows)
    buckets = defaultdict(int)
    for r in rows:
        buckets[r["label"]] += 1
    print("审计基准日 %s ｜ 基线图总数 %d ｜ 去重删除 %d 张" % (today.isoformat(), total, removed))
    for label in ("保留", "降级", "删除"):
        pct = buckets[label] * 100.0 / total if total else 0.0
        print("  %-2s %5d 张  %5.1f%%" % (label, buckets[label], pct))

    noisy = [r for r in rows if r["failures"] >= 5 and r["fp_rate"] >= args.fp_gate]
    fp_noisy = sum(r["false_pos"] for r in noisy)
    fp_all = sum(r["false_pos"] for r in rows)
    ratio = (fp_noisy * 100.0 / fp_all) if fp_all else 0.0
    print("\n假阳性集中度：%d 张图贡献了 %d/%d 次假阳性（%.1f%%）" % (len(noisy), fp_noisy, fp_all, ratio))
    print("先治这 %d 张，CI 红灯量与评审成本会同步下降。" % len(noisy))

    kept_defects = sum(r["real_defects"] for r in rows if r["label"] == "保留")
    all_defects = sum(r["real_defects"] for r in rows)
    print("真缺陷覆盖：保留集覆盖 %d/%d 次历史真缺陷检出（%.1f%%）"
          % (kept_defects, all_defects, (kept_defects * 100.0 / all_defects) if all_defects else 0.0))
    print("这一行是瘦身的验收线：低于 95% 就要回头检查分层规则。")
    print("\n明细已写入 %s" % args.out)


if __name__ == "__main__":
    main()

为什么这么写：脚本的核心不是打标签，而是最后两行输出——假阳性集中度告诉你先治哪里最划算，真缺陷覆盖率告诉你瘦身有没有伤到检出能力。后者是整件事的验收线：删掉一批用例后，历史真缺陷的覆盖面必须几乎不掉，否则瘦身就是砍检出。

踩过的坑有三个。一是 last_defect 这列绝大多数团队没有，需要从缺陷单系统回溯关联，第一次做要花人力，之后每次失败评审顺手补一行。二是去重不能只看文件名相似度，同组件同断点的两张图可能命名完全不同，要按组件与断点这两个语义字段分组。三是降级为语义断言不等于放弃覆盖，它是把「这块区域的像素」换成「结构与文案契约」，关键属性和角色断言必须补上，否则就是纯删除。

七、瘦身前后的对照与验收度量

审计、分类、治理、去重四步做完，这份用例集的变化是这样的：

这张表里最该盯的不是用例数从两千降到六百，而是最后两行：真缺陷覆盖面几乎没掉，检出数量反而涨了——用例数下降是手段，信噪比上升才是目的。

长期挂着三条验收度量：每周红灯数与假阳性占比、每张保留图距上次抓到真缺陷的天数、基线更新提交中带变更说明的比例。任何一条恶化，说明这套东西又在往回滑。

用例集的价值不在数量，而在每一张红灯都有人愿意点开看。