Nuxt 与水合 (Hydration)

为什么修复水合问题很重要

在开发过程中，你可能会遇到水合问题。请不要忽视这些警告。

为什么修复它们很重要？

水合不匹配不仅仅是警告——它们是可能破坏应用程序的严重问题的指标

性能影响

  • 可交互时间增加：水合错误会强制 Vue 重新渲染整个组件树，从而增加你的 Nuxt 应用变得可交互所需的时间
  • 用户体验差：用户可能会看到内容闪烁或意外的布局偏移

功能问题

  • 交互失效：事件监听器可能无法正确绑定，导致按钮和表单无法使用
  • 状态不一致：用户看到的内容与应用程序认为渲染的内容之间，应用状态可能会失去同步
  • SEO 问题：搜索引擎索引的内容可能与用户实际看到的内容不同

如何检测它们

开发控制台警告

在开发过程中，Vue 会在浏览器控制台中记录水合不匹配警告

常见原因

服务端上下文中的纯浏览器 API

问题：在服务端渲染期间使用特定于浏览器的 API。

<template>
  <div>User preference: {{ userTheme }}</div>
</template>

<script setup>
// This will cause hydration mismatch!
// localStorage doesn't exist on the server!
const userTheme = localStorage.getItem('theme') || 'light'
</script>

解决方案：你可以使用 useCookie

<template>
  <div>User preference: {{ userTheme }}</div>
</template>

<script setup>
// This works on both server and client
const userTheme = useCookie('theme', { default: () => 'light' })
</script>

数据不一致

问题：服务端和客户端之间的数据不同。

<template>
  <div>{{ Math.random() }}</div>
</template>

解决方案：使用对 SSR 友好的状态

<template>
  <div>{{ state }}</div>
</template>

<script setup>
const state = useState('random', () => Math.random())
</script>

基于客户端状态的条件渲染

问题：在 SSR 期间使用仅限客户端的条件。

<template>
  <div v-if="window?.innerWidth > 768">
    Desktop content
  </div>
</template>

解决方案：使用媒体查询或在客户端处理

<template>
  <div class="responsive-content">
    <div class="hidden md:block">Desktop content</div>
    <div class="md:hidden">Mobile content</div>
  </div>
</template>

具有副作用的第三方库

问题：修改 DOM 或具有浏览器依赖项的库（标签管理器经常会出现这种情况）。

<script setup>
if (import.meta.client) {
    const { default: SomeBrowserLibrary } = await import('browser-only-lib')
    SomeBrowserLibrary.init()
}
</script>

解决方案：在水合完成后初始化库

<script setup>
onMounted(async () => {
  const { default: SomeBrowserLibrary } = await import('browser-only-lib')
  SomeBrowserLibrary.init()
})
</script>

基于时间的动态内容

问题：根据当前时间更改的内容。

<template>
  <div>{{ greeting }}</div>
</template>

<script setup>
const hour = new Date().getHours()
const greeting = hour < 12 ? 'Good morning' : 'Good afternoon'
</script>

解决方案：使用 NuxtTime 组件或在客户端处理

<template>
  <div>
    <NuxtTime :date="new Date()" format="HH:mm" />
  </div>
</template>

<template>
  <div>
    <ClientOnly>
      {{ greeting }}
      <template #fallback>
        Hello!
      </template>
    </ClientOnly>
  </div>
</template>

<script setup>
const greeting = ref('Hello!')

onMounted(() => {
  const hour = new Date().getHours()
  greeting.value = hour < 12 ? 'Good morning' : 'Good afternoon'
})
</script>

总结

  1. 使用对 SSR 友好的组合式函数：useFetch、useAsyncData、useState
  2. 包裹纯客户端代码：为浏览器特定的内容使用 ClientOnly 组件
  3. 保持数据源一致：确保服务端和客户端使用相同的数据
  4. 避免在 setup 中产生副作用：将依赖浏览器的代码移至 onMounted
你可以阅读 Vue 关于 SSR 水合不匹配的文档以更好地理解水合。