告别Hydration Mismatch：Valaxy SSR兼容与FOUC防护完整指南

Valaxy 是一款下一代静态博客框架，通过 SSG（静态站点生成）在构建期用 Vue SSR 把页面渲染为 HTML。但不少用户从旧版升级后，都会遇到两类典型问题：控制台报错 Hydration Mismatch（水合不匹配）、页面首屏出现无样式闪烁（FOUC）。本文将从零讲清这两个问题的成因，并给出 Valaxy 内置的完整解决方案，帮你快速写出 SSR 兼容的主题、插件与文章。

一、什么是 Hydration Mismatch？

Valaxy 的 SSG 引擎在构建时用 Node.js 环境把组件渲染成纯字符串 HTML——没有 DOM。页面部署后，Vue 在浏览器中"水合"（hydrate）这份 HTML：给元素绑定事件、恢复响应式状态，让页面可交互。

只要服务端输出的 HTML 与客户端重新渲染的结果不一致，Vue 就会报出 Hydration mismatch 警告，轻则控制台刷屏，重则布局错位、目录丢失、链接点不动。

⚠️ 升级注意：Valaxy 曾内置基于 JSDOM 的 vite-ssg 引擎，它在 SSR 期间悄悄提供了 window、document，让依赖浏览器的代码"看似能跑"。v1.0 已移除该引擎，同样的代码现在会直接报错或水合失败。迁移说明见 版本迁移。

四类常见诱因

诱因	典型示例
模板中使用仅浏览器 API	{{ window.innerWidth }}
依赖时间/地区的内容	{{ new Date().toLocaleString() }}
浏览器扩展改写 HTML	广告拦截器注入节点
非标准 HTML 嵌套	<p> 里再嵌 <p>、<a> 里包 <div>

二、4 个告别水合不匹配的实用方案

以下方案均来自框架官方实现与文档，按"从简单到进阶"排序。

1. 用 <ClientOnly> 包裹纯浏览器内容（最常用）

<ClientOnly> 是 Valaxy 内置组件（实现见 ClientOnly.ts），内容只会在浏览器中渲染，SSG 阶段直接跳过。配合 #fallback 插槽可展示占位内容：

<ClientOnly>
  <HeavyChart :data="chartData" />
  <template #fallback>
    <div class="chart-placeholder">图表加载中…</div>
  </template>
</ClientOnly>

2. 用 defineClientComponent 懒加载第三方库

如果第三方库在 import 时就要碰 window/document（而不只是渲染时），用框架提供的 defineClientComponent（源码见 client-component.ts），它会把 import() 推迟到组件在浏览器挂载之后，并支持传入 props、插槽与加载完成回调：

const EchartsChart = defineClientComponent(
  () => import('vue-echarts'),
  [{ option: chartOption, autoresize: true }],
)

3. 逻辑里用 onMounted + ref 读取浏览器信息

只需要在逻辑中读视口宽度、滚动位置等信息时，把访问全局对象的操作移进 onMounted，模板先渲染默认值：

const screenWidth = ref(0)
onMounted(() => {
  screenWidth.value = window.innerWidth
})

4. 用 import.meta.env.SSR 做条件执行 + CSS 媒体查询做响应式

• 在 composables 或 setup 中，用 import.meta.env.SSR 标志包裹仅浏览器的副作用。
• ⚠️ 不要用 v-if 切换移动/桌面布局——服务器不知道访客视口大小，必然水合失败。请改用 CSS 媒体查询控制显隐。

完整示例与主题开发注意事项见官方指南 SSR 兼容性。

三、FOUC 防护：首屏样式如何做到零闪烁

v1.0 移除了 Critical CSS 内联，改为更轻量的 FOUC guard（实现见 fouc-guard.ts）。工作原理分三步：

1. 构建时在 <head> 内联一段 body { opacity: 0 !important }，先隐藏页面；
2. 内联脚本持续监测所有 link[rel="stylesheet"] 的加载状态（含异步切换 media 属性的样式表）；
3. 全部就绪后移除隐藏样式，页面以 0.15s 淡入呈现；超时（默认 5 秒）则强制兜底显示，避免 CSS 加载失败导致白屏。

在 valaxy.config.ts 中可通过 build.foucGuard 调整（文档见 扩展配置）：

build: {
  foucGuard: {
    enabled: true,   // 默认开启
    maxDuration: 5000, // 超时兜底（毫秒），设 0 可禁用
  },
}

四、进阶坑点：Teleport 弹层与 PWA 导航回退

• 弹层容器：弹窗、菜单请统一 Teleport 到框架提供的 #valaxy-teleports 容器（定义于 index.html），SSG 会把弹层内容与水合锚点注入其中；to="body" 的旧写法仍有兼容处理，但新代码建议迁移。
• PWA 用户：若启用 vite-plugin-pwa，务必设置 workbox.navigateFallback: null。否则刷新文章链接时 Service Worker 可能回退返回首页 HTML，Vue 会拿文章页去水合首页 DOM，直接造成 hydration mismatch 与布局错乱。详见 vite-plugin-pwa 配置说明。

五、验证清单：三步确认你的站点已就绪

1. 始终用 SSG 构建验证（如 pnpm demo:build）——开发模式捕获不到 SSR 问题；
2. 检查构建产物 HTML 与客户端渲染结果一致，控制台无 hydration 警告；
3. 用生产构建 + 预览反复切换路由、开合弹层（桌面与移动端），确认无闪烁、无错位。

记住三条黄金法则：浏览器 API 一律延迟到挂载后执行；响应式布局交给 CSS；首屏样式交给 FOUC guard。做到这三点，Hydration Mismatch 与首屏闪烁就会从你的博客里彻底消失。