SSR 服务端渲染原理精讲

// Nuxt 内部简化逻辑
// 服务端：
const html = await renderToString(app)  // 渲染为 HTML 字符串
const payload = serializePayload(state) // 序列化数据状态
 
// 客户端：
const app = createSSRApp(App)
app.mount('#__nuxt')  // Hydration：不会重新创建 DOM，而是"接管"已有 DOM

// 1. Payload 直接注入（避免客户端重新请求数据）
// 服务端获取的数据直接序列化到 HTML 中
// <script>window.__NUXT__ = { data: {...}, state: {...} }</script>
 
// 2. 组件级 Lazy Hydration（实验性）
// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    componentIslands: true,  // 岛屿组件：部分组件延迟水合
  },
})

<!-- 延迟水合：只有进入视口时才激活 -->
<LazyMyComponent />
 
<!-- 永不水合：纯展示组件，不需要客户端交互 -->
<NuxtIsland name="StaticBanner" />

<script setup lang="ts">
// ✅ setup 中的代码在两端都执行
const count = ref(0)
const route = useRoute()
const { data } = await useFetch('/api/data')  // 服务端获取，客户端复用 Payload
 
// ✅ 环境检测
if (import.meta.server) {
  // 仅服务端执行
  console.log('Server: rendering on', process.env.NODE_ENV)
}
 
if (import.meta.client) {
  // 仅客户端执行
  console.log('Client: browser', navigator.userAgent)
}
 
// ✅ onMounted 保证在客户端执行
onMounted(() => {
  // 安全访问 DOM 和浏览器 API
  window.addEventListener('scroll', handleScroll)
  const el = document.getElementById('player')
})
 
// ✅ onServerPrefetch 仅在服务端执行
onServerPrefetch(async () => {
  // 服务端预获取数据（较少使用，useFetch 已自动处理）
  await someServerOnlyFetch()
})
</script>

// ❌ 错误 1：setup 中直接访问浏览器 API
const width = window.innerWidth  // 💥 服务端没有 window
 
// ✅ 修复：在 onMounted 或 import.meta.client 中使用
const width = ref(0)
onMounted(() => {
  width.value = window.innerWidth
})
 
// ❌ 错误 2：setup 中使用 localStorage
const token = localStorage.getItem('token')  // 💥 服务端没有 localStorage
 
// ✅ 修复：使用 useCookie（两端通用）
const token = useCookie('token')
 
// ❌ 错误 3：setup 中操作 DOM
const el = document.querySelector('.player')  // 💥 服务端没有 document
 
// ✅ 修复：使用模板 ref + onMounted
const playerRef = ref<HTMLElement | null>(null)
onMounted(() => {
  playerRef.value?.focus()
})

<script setup lang="ts">
// 方式 1：动态导入 + ClientOnly
const VideoPlayer = defineAsyncComponent(() =>
  import('some-video-player')  // 仅客户端加载
)
</script>
 
<template>
  <ClientOnly>
    <VideoPlayer :url="video.url" />
    <template #fallback>
      <div class="aspect-video bg-gray-200 animate-pulse" />
    </template>
  </ClientOnly>
</template>

// 方式 2：Nuxt Plugin 指定客户端执行
// app/plugins/chart.client.ts（.client 后缀 = 仅客户端）
import Chart from 'chart.js'
 
export default defineNuxtPlugin(() => {
  return {
    provide: { Chart },
  }
})

<!-- 方式 3：.client.vue 后缀的组件 -->
<!-- app/components/VideoPlayer.client.vue -->
<!-- 这个组件文件本身只在客户端渲染 -->
<template>
  <div ref="playerEl" />
</template>
 
<script setup lang="ts">
import Plyr from 'plyr'
 
const playerEl = ref<HTMLElement>()
onMounted(() => {
  new Plyr(playerEl.value!)
})
</script>

// 在 setup、插件、中间件中获取
const nuxtApp = useNuxtApp()
 
if (import.meta.server) {
  const ssrContext = nuxtApp.ssrContext
  // ssrContext 包含：
  // - event: H3 请求事件（Nitro 的 HTTP 请求对象）
  // - url: 当前请求 URL
  // - payload: 要发送给客户端的数据
  // - head: SEO 头部信息
  // - teleports: Teleport 渲染内容
}

// app/plugins/response-headers.server.ts
export default defineNuxtPlugin((nuxtApp) => {
  const event = useRequestEvent()
  if (!event) return
 
  // 设置自定义响应头
  setResponseHeader(event, 'X-Powered-By', 'Nuxt4')
  setResponseHeader(event, 'Cache-Control', 'public, max-age=60')
 
  // 根据页面设置不同的缓存策略
  nuxtApp.hook('page:finish', () => {
    const route = useRoute()
    if (route.path.startsWith('/api')) {
      setResponseHeader(event, 'Cache-Control', 'no-cache')
    }
  })
})

<!-- 服务端渲染的 HTML 中会包含 -->
<script>
  window.__NUXT__ = {
    data: {
      "videos-123": {  // useFetch 的缓存 key
        id: "123",
        title: "AI 视频教程",
        views: 12500
      }
    },
    state: {
      "auth:user": { id: "u1", name: "Alice", role: "admin" }
    }
  }
</script>

// app/plugins/payload-types.ts
export default defineNuxtPlugin((nuxtApp) => {
  // 注册自定义类型的序列化/反序列化
  definePayloadReducer('VideoTimestamp', (value) => {
    if (value instanceof VideoTimestamp) {
      return { seconds: value.toSeconds() }
    }
  })
 
  definePayloadReviver('VideoTimestamp', (data) => {
    return VideoTimestamp.fromSeconds(data.seconds)
  })
})

// ✅ 使用 pick 只选取需要的字段（减少 Payload 体积）
const { data } = await useFetch('/api/videos', {
  pick: ['id', 'title', 'thumbnail'],  // 只传输这 3 个字段到客户端
})
 
// ✅ 使用 transform 精简数据
const { data } = await useFetch('/api/videos', {
  transform: (videos) => videos.map(v => ({
    id: v.id,
    title: v.title,
    thumbnail: v.thumbnail,
  })),
})
 
// ❌ 避免：将完整的 API 响应（可能含大量无用字段）直接传输
const { data } = await useFetch('/api/videos')
// 如果 API 返回 100 个字段，全部都会序列化到 Payload

<!-- ❌ 错误：服务端和客户端的时间不同 -->
<template>
  <span>{{ new Date().toLocaleString() }}</span>
</template>
 
<!-- ✅ 修复：使用 ClientOnly -->
<template>
  <ClientOnly>
    <span>{{ new Date().toLocaleString() }}</span>
    <template #fallback>
      <span>加载中...</span>
    </template>
  </ClientOnly>
</template>

<script setup lang="ts">
// ❌ 错误：服务端没有 window，isMobile 始终为 false
const isMobile = ref(window.innerWidth < 768)
</script>
 
<script setup lang="ts">
// ✅ 修复：使用 onMounted 延迟判断
const isMobile = ref(false)
onMounted(() => {
  isMobile.value = window.innerWidth < 768
})
</script>

<!-- ❌ 错误：服务端没有 localStorage，条件结果不同 -->
<template>
  <div v-if="isLoggedIn">Welcome</div>
</template>
<script setup>
const isLoggedIn = !!localStorage.getItem('token')
</script>
 
<!-- ✅ 修复：使用 useCookie 两端一致 -->
<script setup>
const token = useCookie('token')
const isLoggedIn = computed(() => !!token.value)
</script>

<!-- ❌ 错误：<p> 内不能嵌套 <div> -->
<p><div>内容</div></p>
 
<!-- ✅ 修复：使用合法嵌套 -->
<div><div>内容</div></div>

// nuxt.config.ts — 开发环境启用详细水合不匹配警告
export default defineNuxtConfig({
  debug: true,  // 启用 Vue 的水合不匹配详细日志
})

<template>
  <!-- 视频播放器：依赖浏览器 API -->
  <ClientOnly>
    <VideoPlayer :url="video.url" />
    <template #fallback>
      <div class="aspect-video bg-gray-200 flex items-center justify-center">
        <LoadingSpinner />
      </div>
    </template>
  </ClientOnly>
 
  <!-- 实时时间显示 -->
  <ClientOnly>
    <LiveClock />
    <template #fallback>
      <span>--:--:--</span>
    </template>
  </ClientOnly>
</template>