Next.js 视觉测试：保护 React SSR 应用的完整指南
要点
- Next.js 提供多种渲染模式（SSR、SSG、ISR、App Router），每种都可能为同一页面产生不同的视觉结果
- React hydration 是传统功能测试无法发现的视觉回归的主要来源
- 基于 Storybook 的方法无法测试 Next.js 页面在生产条件下的实际渲染
- 一个 framework-agnostic 的视觉测试工具，捕获浏览器中的最终结果，是对抗 Next.js 视觉回归的唯一可靠保障
视觉测试，根据 ISTQB（International Software Testing Qualifications Board）的定义，是指*"通过将参考截图与应用程序的当前状态进行比较，验证软件的用户界面是否按照预期的视觉规范显示"*（ISTQB Glossary, Visual Testing）。
当你将这一原则应用到 Next.js 应用时，情况会变得相当复杂。Next.js 不是一个简单的 React 应用。它是一个提供至少四种不同渲染模式的框架——有时在同一页面上。而每种渲染模式都可能产生微妙不同的视觉结果，原因是你的单元测试和集成测试永远无法检测到的。
根据 State of JS 2024，Next.js 被 58% 的 React 开发者在生产中使用。Stack Overflow Developer Survey 2024 将其列为仅次于 React 本身的最常用 Web 框架。这不是小众市场：这是专业 React 应用的事实标准。然而，大多数使用 Next.js 的团队没有适应其特性的视觉测试策略。
本文将解决这个问题。
为什么 Next.js 让视觉测试更重要，而不是更不重要
在开发团队中经常听到这样的论点："Next.js 为我们管理渲染，我们不需要视觉验证每个页面。"这与现实恰恰相反。
Next.js 使视觉测试更加关键，正是因为它增加了渲染路径。当你使用 Create React App 的简单 React SPA 时，渲染是可预测的：一切都在客户端的浏览器中完成。视觉结果是确定性的。使用 Next.js，同一页面可能在第一次请求时在服务端渲染，然后在客户端 hydrate，然后在客户端导航时部分重新渲染。这些步骤中的每一个都可能引入视觉差异。
Hydration 问题
Hydration 是 React 获取服务端生成的 HTML 并在客户端"重新激活"它的过程，通过附加事件监听器和同步虚拟 DOM。理论上，hydration 前后的视觉结果应该相同。实际上，很少能达到 100%。
原因是多方面的。服务端计算的样式不考虑实际的浏览器窗口大小。依赖于 window 或 document 的组件在服务端显示 fallback，在客户端显示实际内容。Web 字体在服务端渲染时并不总是可用，导致 hydration 后出现无样式文本闪烁（FOUT）。CSS 动画在 hydration 时开始，而不是在页面加载时。
结果：服务器发送的内容和用户在 hydration 后看到的内容之间存在视觉差距。这种差距通常很微妙——几个像素的偏移、文本重排、图片跳动。但它是真实的，并且会降低用户体验。
没有单元测试可以检测到这个问题。检查 DOM 中元素存在的集成测试也看不到。只有视觉测试——在完全 hydration 后在真实浏览器中捕获渲染页面的图像——才能确认最终结果符合你的预期。
四种渲染模式及其视觉陷阱
Next.js 提供四种主要的渲染策略，每种从视觉角度都有其特定的陷阱。
静态渲染（SSG）在构建时生成 HTML。最可预测，但注意：如果你的数据在两次构建之间发生变化，静态页面会显示过时数据。
服务端渲染（SSR）在每次请求时生成 HTML。内容本质上是动态的。同一 URL 可能根据时间、登录用户和数据库数据产生不同的视觉渲染。视觉测试必须处理这种变化性。
增量静态再生（ISR）是混合模式：页面是静态的但周期性地在后台重新生成。视觉陷阱是新旧版本之间的过渡。
App Router，在 Next.js 13 中引入，添加了 Server Components、streaming 和嵌套 layouts。Server Components 从不在客户端执行。Client Components 经历 hydration。同一页面混合了两者。结果是渐进式渲染，内容分块出现——每块都可能引入视觉偏移。
Next.js 应用的视觉测试方法
Playwright：暴力方法
Playwright 由 Microsoft 开发，是 2026 年最全面的浏览器自动化框架。它测试真实页面，在真实浏览器中，完整渲染（SSR + hydration + CSS + 字体）。但它需要编写和维护测试脚本，截图比较是基础的像素级比较，且基线基础设施是你的责任。对于大多数团队来说，系统性视觉测试的维护成本太高。
Chromatic 通过 Storybook：隔离组件的幻觉
Chromatic 不测试你的 Next.js 页面——它测试 Storybook 中的隔离组件。Next.js 中最危险的视觉回归来自组件之间的交互、整体页面布局、SSR 渲染、hydration 和 App Router 的嵌套 layouts。Chromatic 永远看不到这些问题，因为它永远看不到完整的页面。
Delta-QA：真实页面的视觉测试，无需代码
Delta-QA 采用截然不同的方法。它捕获你的真实页面的截图——你的用户看到的那些——并在应用的两个版本之间进行比较。
Delta-QA 不需要知道你的应用使用 Next.js、React、App Router 还是 Pages Router。它捕获浏览器中的最终渲染结果，在 SSR 后、hydration 后、字体加载后、客户端 JavaScript 执行后。它比较的正是你的用户看到的。
Delta-QA 以 no-code 方式工作：你配置要监控的 URL、要捕获的视口，工具完成剩余工作。对于 50 页面、三个视口的 Next.js 应用，每次部署你可以获得 150 次自动视觉捕获，无需编写一行测试代码。
Next.js 特有挑战及应对方法
动态内容
Delta-QA 允许你定义页面上的排除区域：你指出包含可变内容的区域，工具在比较时忽略它们。
字体和 FOUT
Delta-QA 原生集成了等待字体完全加载后再捕获的功能，确保截图反映页面的稳定状态。
动画和过渡
Delta-QA 原生提供禁用 CSS 和 JavaScript 动画的选项。对于 CSS 动画，它注入强制 animation-duration: 0s 和 transition-duration: 0s 的样式表。
App Router 嵌套 Layouts
父 layout 的更改会影响所有子页面。如果你捕获 50 个页面且父 layout 发生变化，所有 50 个捕获都会显示差异。你在部署前立即看到影响范围。
将视觉测试集成到 Next.js CI/CD 流水线
推荐流程：推送代码到分支，CI 构建 Next.js 应用并部署到预览环境（Vercel、Netlify 或你自己的基础设施），Delta-QA 捕获预览环境的截图并与生产基线比较，结果直接显示在你的 merge request 或 pull request 中。
这个工作流程与 Next.js 和 Vercel 特别自然，后者会为每个分支自动创建预览环境。
要跟踪的指标
生产前视觉回归检测率、误报率、平均审查时间、覆盖页面数与总页面数之比。
常见问题
视觉测试能替代 Next.js 的单元测试和集成测试吗？
不能。视觉测试是补充，不是替代。单元测试验证组件逻辑。集成测试验证组件协同工作。视觉测试验证最终结果——用户看到的——符合预期。三者都是完整覆盖所必需的。
如何在视觉测试中处理 Next.js Server Components？
Server Components 不会为视觉测试带来特定困难。由于视觉测试捕获浏览器中的最终结果，它不关心组件是在服务端还是客户端渲染的。Delta-QA 像用户一样看到页面。
Next.js 应用应该测试多少个视口？
至少三个：移动端（375px）、平板（768px）和桌面端（1440px）。App Router 的嵌套 layouts 可能在每个断点表现不同，使响应式覆盖比经典 SPA 更加关键。
视觉测试会减慢 Next.js CI/CD 流水线吗？
使用 Delta-QA，捕获和比较与流水线的其余部分并行运行。50 页面三个视口的应用，预计整个过程需要两到五分钟。
可以将视觉测试用于 Next.js 的 draft mode 功能吗？
是的，甚至推荐这样做。draft mode 允许预览来自 headless CMS 的未发布内容。视觉测试可以验证未发布内容不会在发布前破坏布局。
Delta-QA 能与 Next.js Middleware（重定向、rewrites、A/B testing）一起工作吗？
是的。Next.js Middleware 在 Edge 服务器级别运行，在页面渲染之前。Delta-QA 捕获所有 Middleware 执行后的最终结果。
结论：Next.js 需要适应其复杂性的视觉测试
Next.js 是一个强大的框架，彻底改变了 React 开发。但这种强大以渲染复杂性为代价，大多数团队低估了这一点。SSR、ISR、App Router、Server Components、streaming、嵌套 layouts——每个功能都增加了一条可能产生意外视觉结果的渲染路径。
视觉测试对于 Next.js 应用不是奢侈品。而是必需品。Delta-QA 正是为此而设计：在真实浏览器中捕获你的真实页面，在完整渲染后，当视觉发生变化时提醒你。无需代码，无需脚本维护。
如果你使用 Next.js 开发但还没有视觉测试策略，你就是在盲飞。是时候纠正了。