自动化视觉回归必须控制动态干扰、统一渲染环境、明确差异归属，否则90%失败为误报；Recharts强制Docker内执行以锁死字体渲染、抗锯齿、设备像素比；pixelmatch需分区域设防而非盲目调高阈值；动态内容须拦截API或隐藏DOM；基线更新须经PR Review、设计确认、全矩阵验证及diff图留痕。
不能只跑截图比对就叫“自动化视觉回归”——必须控制动态干扰、统一渲染环境、明确差异归属，否则90%的失败都是误报。
为什么本地直接跑 Playwright/Cypress 截图会频繁失败
常见错误现象：test-vr 在本机运行时大量报 127 pixels differ，但 UI 看不出变化；npm run test-vr 在 Docker 外执行被明确禁止（见 test-vr/README.md）。
根本原因不是工具不行，而是渲染环境不可控：
- 字体渲染：macOS 的 Core Text 与 Linux 的 FreeType 对同一
font-weight渲染出的 subpixel 位置不同 - 抗锯齿开关：Chrome 启动参数未统一时，
--disable-features=UseSkiaRenderer缺失会导致阴影边缘抖动 - 设备像素比：本地
deviceScaleFactor: 2与 CI 中固定为1会直接让所有 baseline 失效
Recharts 官方强制要求所有 test-vr 流程必须在 Docker 内执行，就是为锁死这三者。别省那几分钟构建时间。
立即学习“前端免费学习笔记（深入）”；
如何用 pixelmatch 控制容差而非盲目调高 threshold
错误做法：把 pixelmatch 的 threshold 从 0.1 改成 0.3，结果掩盖了真实布局偏移。
正确思路是分区域设防：
- LOGO 区域：用
excludeAreas: [{x: 20, y: 15, width: 120, height: 40}]显式跳过，避免字体微调触发失败 - 数据表格区：保留默认
threshold: 0.1，因行高/边框错位必须精确捕获 - 空白背景区：用
includeAA: true允许抗锯齿差异，但仅限该区域调用
示例代码中不要写全局 pixelmatch(img1, img2, ...)，而应先用 canvas.getContext('2d').getImageData() 提取 ROI 区域再比对。
Cypress + cypress-image-snapshot 如何屏蔽动态内容
典型场景：倒计时组件、实时刷新的股票价格、随机推荐卡片——它们让 baseline 永远无法稳定。
必须在截图前做两件事：
- 拦截 API：用
cy.intercept('/api/price', { price: 123.45 })固定返回值，而非等接口自然响应 - 隐藏/冻结 DOM：对倒计时容器执行
cy.get('.countdown').invoke('hide')或注入 CSSvisibility: hidden
注意：cypress-image-snapshot 的 percy 模式不支持动态元素白名单，必须退回到原始 DOM 操作层处理。Percy 的 ignoreRegions 是声明式配置，而 Cypress 插件需要命令式干预。
基线快照更新必须走 PR Review 流程
最危险操作：npm run test-vr:update 直接提交到 main 分支。
真实项目中，baseline 更新需满足三个条件才允许合入：
- 变更由设计确认：如按钮圆角从
4px改为6px，需附 Figma 链接 - 全矩阵通过：同一 story 必须在 Chrome/Firefox/Safari + light/dark 主题共 6 种组合下全部生成一致新快照
- diff 图留痕：更新命令生成的
.diff.png必须作为 PR 附件上传，供 QA 人工复核
自动化的终点不是“少点人点鼠标”，而是把“谁改了哪块像素”变成可追溯、可审计、可回滚的动作。漏掉任意一环，视觉测试就会从质量护栏退化为发布阻塞器。
