AI 把界面改崩了你却不知道：vibe 项目的视觉回归测试实战

AI 改 UI 的三种崩法，你都遇到过

vibe 开发者最高频的动作，就是对 AI 说"把这个页面改一下"。而 AI 每次重写页面，都可能悄悄留下一些"小礼物"。第一种崩法叫位移 8px：你让 AI"把按钮组往右挪一点"，它重写了整个 flex 布局，按钮是挪过去了，但旁边的输入框也跟着漂了 8px。功能测试全绿——按钮能点、表单能提交，可页面就是看着别扭，你说不上来哪里不对。

第二种崩法是深色模式漏改。你的项目有深浅两套主题，AI 改完浅色模式觉得大功告成，深色模式里新加的那块卡片还是白底，配着白色文字——白底白字，隐形了。这种 bug 在开发者的浅色屏幕上永远看不见，第一次被发现往往是用户截图发到群里。

第三种崩法最气人：断点塌掉。桌面端好好的，AI 顺手"优化"了一下响应式，375px 宽度的手机上两张卡片叠在了一起，文字压着文字。你平时用桌面浏览器开发，根本不会打开手机宽度看一眼。

这三种崩法的共同点是：E2E 测试全绿，TypeScript 编译全过，肉眼不逐像素对比根本发现不了。AI 改 UI 的问题从来不是"功能坏了"，而是"长得不一样了"——而"长得一样"这件事，你的测试体系里根本没人负责。

视觉回归是什么、不是什么

视觉回归测试做的事很直白：把页面长什么样，当成一种测试断言。第一次运行时，给关键页面拍一张"标准答案"（基线图，baseline）；之后每次代码变更，再拍一张新的，逐像素对比。差一个像素，就告诉你。

它不是 E2E 的替代品。E2E 回答"按钮能不能点"，视觉回归回答"按钮长得和上次一样不一样"。这两个问题正交：按钮位移 8px，E2E 全绿；按钮点不了但长得没变，视觉回归全绿。你需要的是两者，不是二选一。

也别把它和组件快照测试（snapshot test）搞混。快照测试对比的是 DOM 结构或组件渲染输出——AI 把 div 换成 section、class 名从 btn-primary 变成 btn-accent，快照会红，但页面可能长得一模一样；反过来，AI 改了一行 CSS 让按钮漂了 8px，DOM 快照全绿，页面却变了。快照测的是"代码结构没变"，视觉回归测的是"人眼看到的没变"。对 vibe 项目来说，后者重要得多，因为 AI 重写代码时结构天天变，但用户只关心看起来一不一样。

先打一针预防针：视觉回归最大的敌人不是漏报，是误报。字体在不同机器上渲染差半个像素、CSS 动画抓到中间帧、页面上的"3 分钟前"每分钟都在变——这些都会让 diff 变红。一个误报率高的视觉回归套件，下场永远是"大家开始忽略红灯"，然后它就死了。所以这篇指南一半篇幅讲怎么接入，一半篇幅讲怎么治理误报。只讲接入不讲误报的视觉回归教程，都是耍流氓。

基线图是整套机制的核心资产：它既是"标准答案"，也是"变更记录"。谁更新了基线、为什么更新，必须像代码评审一样可追溯。一个没人敢更新的基线库会腐烂，一个谁都能随手更新的基线库等于没有——这个度，第 4 节细讲。

最小可行方案：Playwright 截图断言，一行接入

如果你已经在用 Playwright 写 E2E，那么视觉回归的接入成本是一行代码：await expect(page).toHaveScreenshot()。第一次运行生成基线图，之后每次运行自动对比。不需要新框架，不需要新服务，不需要学新概念——这是我最推荐一人 vibe 项目的起点。

但直接裸用会立刻被误报淹没，所以第二行代码同样重要：mask 参数。时间戳、用户头像、随机推荐位——这些每次渲染都长得不一样的区域，必须在截图前遮掉。toHaveScreenshot({ mask: [page.locator('.timestamp')] })，把动态区域涂黑再比。这不是作弊，这是诚实：你本来就不关心时间戳长什么样，别让它污染你真正关心的布局断言。

第三个要配的是失败产物。CI 里截图对比失败时，Playwright 会自动产出三张图：基线图（应该长这样）、实际图（现在长这样）、差异图（红框标出哪里不一样）。确保你的 CI 把这三张图当成 artifact 上传，而不是只打印一行"2 snapshots differ"。没有 diff 图的红灯等于没有信息，开发者只能本地重跑——本地重跑三次，耐心就用完了。

首次生成基线图时有个仪式感很强的步骤：把每一张基线图亲自打开看一遍。听起来像废话，但很多人第一次运行是"跑完就当对了"。基线图是你未来所有对比的"标准答案"，如果第一张就是错的（比如页面没加载完就截了图），之后所有的"通过"都是错的。花 10 分钟一张张看，这是整个视觉回归体系里 ROI 最高的 10 分钟。

从哪几个页面开始？我的建议：首页、核心转化页（定价页/结账页）、AI 最常改的那个页面。一共 3-5 个页面，半天接完。贪多的一次性全量接入，误报会把你淹没，然后你会得出"视觉回归不靠谱"的错误结论——错的是节奏，不是技术。

还有一个容易漏的维度：视口。同一张页面，桌面 1440px 和手机 375px 是两张完全不同的截图，断点处的布局问题只会在小视口暴露。Playwright 里给同一个测试配两个 viewport 各跑一遍，成本翻倍但覆盖的是两类 bug。我的排序是：先桌面端跑顺，再加手机视口——因为桌面端的误报治理经验（mask 哪些区域、阈值设多少）可以直接复用，加视口只是"再跑一遍"，心智负担很小。

基线图放哪、怎么更新：这是门管理学问

页面少（10 个以内），基线图直接进 Git。小 PNG 一张几十 KB，Git 毫无压力，还附赠版本历史：git log 就能看到"首页基线在 10 月 3 日更新过，因为改版了 Hero 区"。页面多（几十上百），进对象存储（S3 / R2），仓库里只存索引文件。分界线很主观，我的经验是：git status 开始让你觉得基线图碍眼时，就是迁出去的时候。

更新基线的工作流必须长这样：有意改 UI → 跑测试 → 在 PR 里看 diff 图 → 人确认后更新基线。四个环节缺一不可，尤其是"人确认"。最危险的反模式是"测试红了就自动更新基线"——这等于把"标准答案"交给了正在被测试的代码，视觉回归当场变成行为艺术。基线更新必须是一个显式的、带理由的动作，和代码评审同级。

我见过基线库腐烂的完整过程：团队一开始很认真，每张基线图都人眼确认；两个月后页面多了，更新基线变成"点一下通过"，理由栏填"常规更新"；又过了一个月，有人为了让 CI 变绿，把明显错位的页面也"更新"成了新基线——从那天起，视觉回归测的就不再是"对不对"，而是"和上次错得一不一样"。基线库的公信力一旦丢掉，重建比重建代码库还难。所以立个铁规矩：基线更新的 PR 描述里必须写"变了哪里、为什么变"，少于 20 个字不给过。形式主义，但管用。

给 AI 下指令时也要同步：告诉它"改完 UI 后跑视觉回归，diff 变红先自己看差异图，确认是预期变更再提交基线更新"。AI 其实很擅长看 diff 图——红框标出来的区域，它一眼就知道自己动了哪里。把"截图对比通过"写进 AI 的完成定义（Definition of Done），让它自己跑、自己看、自己修。你会发现，AI 修自己引入的视觉回归，比修逻辑 bug 快得多，因为证据（diff 图）太直观了。

治理误报的四招：先把噪音掐掉

误报有四个主要来源，每个都有对应的标准解法。按顺序治理，治理完一轮，你的视觉回归套件会从"天天狼来了"变成"红了就是真有事"。

第一招：固定测试字体。不同机器、不同系统版本的字体渲染能差出半个像素，足以让整页 diff 变红。做法是测试环境强制加载同一套字体文件（WOFF2 打包进仓库或从固定 CDN 拉），并且关掉系统字体回退。代价是截图里的字体和你本地可能略有不同——没关系，你要的是"每次都一样"，不是"和设计稿一模一样"。

第二招：全局关闭 CSS 动画。测试时注入一段 CSS：* { animation: none !important; transition: none !important; }。动画的中间帧是截图，抓到的每一帧都长得不一样，diff 必红。有人担心"关了动画测的还是真实页面吗"——是的，因为你要断言的是布局，不是动画。动画本身用专门的动效测试（或人眼）覆盖，别和像素 diff 混在一起。

第三招：冻结时间。Mock 掉 Date，让"3 分钟前""2026-10-22"这类文本在测试里永远显示同一个值。Playwright 有官方的时钟 mock，几行代码的事。时间是动态内容里最隐蔽的一种——它不像头像那样一眼能看出来，但它每分钟都在变。

第四招：mask 动态区 + 设阈值。头像、推荐位、广告位，用 mask 遮掉；剩下的微小差异，用 maxDiffPixels 设一个阈值（比如 100 个像素）。阈值不是"放水"，是承认"亚像素渲染差异客观存在"。阈值设多少？从 0 开始，每次被误报烦到就放宽一点，稳定在一个"误报消失、真问题还能抓住"的点上。这个点每个项目不一样，自己调。

特别点名 AI 生成页面的两大误报源：随机渐变背景和 lorem ipsum 占位文本。AI 特别爱给卡片加"好看的渐变"，每次生成的渐变参数还不一样——整张截图没有一个像素是对得上的。对策：要么让 AI 用固定色值（把渐变参数写死在 prompt 里），要么把渐变区域整个 mask 掉。占位文本同理：lorem ipsum 每次长度不一样，撑开的布局每次都不一样，mask 或替换成固定文案，二选一。

进阶：Chromatic / Percy 值不值那个价

Playwright 原生方案跑顺之后，你会开始眼馋 Chromatic 和 Percy：它们在 PR 里自动贴出 diff 图、支持跨浏览器渲染、基线管理有 UI。体验确实好，问题是价格。免费额度对个人项目够用，但页面一多就开始收费，而 vibe 项目的页面数增长往往比你预想的快。

我的结论很直接：一人 vibe 项目，页面少，Playwright 原生够用。升级的触发条件只有一个——"需要设计师（或合伙人）评审每次 UI 变更"。当你需要把 diff 图发给不懂代码的人看、等人点头才合并时，Chromatic 的 PR 评论体验就值回票价了。在那之前，原生方案省下的钱和复杂度，都是实实在在的。

决策时可以算两笔账。第一笔是误报成本：原生方案的误报治理要你自己动手（就是第 5 节那四招），SaaS 方案帮你做了智能 diff（忽略抗锯齿、自动识别动态区），省的是调阈值的时间。第二笔是协作成本：只有你一个人看 diff，原生够了；要给三个人看，SaaS 的评论和审批流就值钱了。一人项目两笔账都是零，所以答案是原生。等你开始为"给别人看 diff"付费时，说明你的项目已经大到需要这笔钱了——那是好事。

还有一个中间选项：把 Playwright 的 diff 图自动贴到 PR 评论里（CI artifact + 一个 bot 脚本，半天能写完）。80% 的 Chromatic 体验，0 成本。很多团队卡在"原生太糙、SaaS 太贵"之间，其实缺的只是这半天的胶水代码。

放进 AI 工作流的位置：让 AI 自己对 diff 负责

视觉回归最大的价值不在 CI 里，而在 AI 的工作循环里。标准动作是：每次让 AI 大改 UI 之后，跑一次视觉回归。不是每天跑一次定时任务，是"改完就跑"。vibe 开发的变更频率太高了，定时任务的粒度根本对不上。

更进一步，把截图对比写进给 AI 的 Definition of Done："本次 UI 变更完成的标准：1）功能测试通过；2）视觉回归无非预期 diff；3）如有预期内的视觉变更，基线已更新并在 PR 描述里说明。"AI 拿到这个 DoD，会自己跑测试、自己看 diff 图、自己判断"这个红框是我预期的改动还是手滑"。你 review PR 时，看到的不再是"我改了页面"，而是"改了页面，diff 在这里，基线已更新"——信息密度完全不是一个级别。

给 AI 的 prompt 可以再具体一点，直接告诉它工作流："改完 UI 后执行 npx playwright test --grep @visual；如果截图对比失败，先看差异图的红框区域，判断是预期变更还是意外；预期的，在 PR 描述里写明变更理由并更新基线；意外的，自己修完重跑，直到全绿。"把判断标准也给它："位移超过 5px、颜色变化、元素遮挡属于必须修的意外；文案微调、间距 1-2px 浮动属于可接受。"你给的判断标准越具体，AI 的误判就越少——这和带人的道理一样：标准模糊，执行就靠猜。

这里有个反直觉的结论：AI 反而比人类更适合做视觉回归的"第一响应人"。人类看 diff 图容易疲劳，看到第三张红框就开始"应该没事吧"；AI 不会疲劳，它会老老实实把每个红框和你的变更意图对一遍。当然，最终拍板更新基线的必须是人——AI 负责发现和解释，人负责决策。这个分工别反了。

检查清单：视觉回归 8 项自查

1. 基线图有人确认过：每一张基线图都是人眼确认"这是对的"之后存的，不是第一次运行自动生成的。
2. 动态区域已 mask：时间戳、头像、推荐位、广告位，截图前全部遮掉。
3. 动画已关闭：测试注入全局 animation: none，不再抓到中间帧。
4. 字体固定：测试环境用同一套字体文件，跨机器渲染一致。
5. 阈值合理：maxDiffPixels 设了一个"误报消失、真问题能抓住"的值，不是 0 也不是无限大。
6. CI 失败会通知：diff 变红时，三张图（基线/实际/差异）自动上传为 artifact 并通知到人。
7. 基线更新走 PR：更新基线是显式动作，带理由，经过人眼确认，绝不自动。
8. AI 的 DoD 里写了截图对比：给 AI 的完成定义包含视觉回归，改完 UI 它自己跑、自己看 diff。

视觉回归的本质，是给"页面长什么样"这件事立一个可执行的标准。vibe 时代之前，这个标准靠设计师人眼；vibe 时代，AI 一天能改 20 版页面，人眼根本跟不上。你不把"长得一样"写成测试，AI 就会用"长得差不多"糊弄过去——而"差不多"，是所有视觉腐烂的开始。一行 toHaveScreenshot()，今天就可以加上。

最后算一笔账：接入成本是半天（3-5 个页面、一行断言、四个误报招式），之后每次 AI 改版多花 2 分钟跑测试。回报是：你再也不用在用户截图发到群里之后，才知道深色模式里有一块白底白字；你 review AI 的 PR 时，有 diff 图告诉你它到底动了哪里。对于一天让 AI 改十几次页面的 vibe 开发者来说，这笔账怎么算都是赚的。视觉债务和代码债务一样，越早立规矩，利息越低。