前端 SSR 实战：Nuxt 3 的 SEO 与 Hydration

Nuxt 3 SSR 实战

本博客前端使用 Nuxt 3 的服务端渲染模式。SSR 的最大收益是 SEO——搜索引擎直接拿到完整 HTML，无需执行 JavaScript。

数据获取策略

Nuxt 3 提供了三个数据获取 composable：

<script setup>
// 1. useAsyncData — SSR 阶段执行，数据嵌入 HTML
const { data } = await useAsyncData('home', () =>
  get('/api/articles', { page: page.value, size: 24 }),
  { watch: [page] }
)

// 2. useLazyAsyncData — 客户端执行，不阻塞页面渲染
const { data: siteInfo } = useLazyAsyncData('site-info', () =>
  get('/api/site').catch(() => ({}))
)

// 3. useFetch — useAsyncData 的封装，自动处理 baseURL
const { data } = await useFetch('/api/articles')
</script>

区分 SSR 和客户端数据的标准：

• 首屏必须展示的内容 → useAsyncData（文章列表、文章详情）
• 非关键的内容 → useLazyAsyncData（站点信息、作者资料）
• 用户操作触发的内容 → 客户端手动 fetch（评论提交、搜索）

分页与数据刷新

useAsyncData 默认缓存 key 是固定的，当页面查询参数变化时不会自动刷新。解决办法是使用 watch 选项：

const { data } = await useAsyncData(
  'home',
  () => get('/api/articles', { page: page.value, size: 24 }),
  { watch: [page] }
)

watch: [page] 让 Nuxt 监听 page 这个 reactive ref，变化时自动重新执行查询函数并更新 UI。

组件自动导入

Nuxt 3 支持 components/ 目录下的组件自动导入，无需手动 import：

// nuxt.config.ts
components: {
  dirs: [
    '~/components/base',   // 基础组件（GlassCard, Pagination...）
    '~/components/blog',   // 业务组件（ArticleCard, CommentSection...）
    '~/components/search',
    '~/components/admin',
  ],
},

模板中直接用 <GlassCard> 即可，Nuxt 按目录优先级查找。如果多个目录有同名组件，前面的目录优先。

Hydration 踩坑

Vue 3 的 hydration 机制要求 SSR 输出和客户端首次渲染的 DOM 完全一致。本博客遇到过的三个典型问题：

问题 1：`` 标签差异

症状：Hydration children mismatch on <a>，导航栏中的 NuxtLink 报错。

# 终端 1：后端 API
cd backend && uvicorn main:app --reload --port 8001

# 终端 2：前端 dev server
cd frontend && npm run dev  # 端口 3000

# 前端通过 Vite proxy 代理 API 请求到 8001