条件渲染解决 Hydration Error 后 Back button 返回白屏
结论
不建议用页面级的 if (!isHydrated) return null 长期处理 Hydration Error。这种写法让服务端和客户端首次渲染时都不输出内容,暂时避开了差异,却会带来一段白屏时间,也失去了 SSR 原本的作用。
可以按下面的方式处理:
- 定位并修复服务端与客户端的实际输出差异。
- 只隔离依赖浏览器环境的局部组件,让页面其他部分正常渲染。
- 必须判断客户端环境时,优先使用
useSyncExternalStore,或者确保服务端和客户端首次渲染相同的占位内容。 - 确认问题与浏览器的 Back/Forward Cache(BFCache)有关后,再通过
pageshow处理页面恢复,不要依赖useEffect再次执行。
isHydrated 为什么会掩盖问题
useEffect 不是“hydration 完成回调”,它只会在组件提交到浏览器后执行。
下面这段代码在服务端渲染时返回 null,客户端第一次渲染时也返回 null,两边的输出因此暂时一致:
const [isHydrated, setIsHydrated] = useState(false);
useEffect(() => {
setIsHydrated(true);
}, []);
if (!isHydrated) {
return null;
}
return <PageContent />;
Hydration Error 可能会因此消失,但也会产生几个问题:
- 服务端不再输出实际的页面内容。
- 页面要等 JavaScript 加载并执行 effect 后才会显示。
- 如果 JavaScript 报错、受阻或尚未执行,页面会一直空白。
- 页面恢复、冻结和重新激活等生命周期都依赖这一次状态切换。
这种写法实际上更像一个 client-only 渲染开关,原来的 hydration 差异并没有得到修复。
Back 返回时不一定会重新执行 useEffect
浏览器使用 BFCache 时,返回上一页通常不会重新加载页面,而是恢复此前被冻结的文档和 JavaScript 状态。组件没有重新挂载,useEffect(() => {}, []) 也就不会再次执行。
如果用户离开页面前 isHydrated 已经变成 true,BFCache 正常恢复后,原有内容通常仍会保留。因此,仅凭持续白屏这一现象,不能认定原因是“effect 已执行,但事件监听器没有恢复”。还要检查以下情况:
- 页面被冻结时,状态仍是
isHydrated === false。 - hydration 或后续渲染期间出现了未捕获异常。
- 浏览器扩展或第三方脚本改动了 React 管理的 DOM。
- 页面恢复后,某段生命周期代码清空了内容。
- 页面并未进入 BFCache,而是重新加载后再次遇到原来的 hydration 问题。
可以先记录 pageshow 事件,确认页面是否从 BFCache 恢复:
useEffect(() => {
const handlePageShow = (event: PageTransitionEvent) => {
console.log("pageshow", {
persisted: event.persisted,
navigationType: performance.getEntriesByType("navigation")[0]?.type,
});
};
window.addEventListener("pageshow", handlePageShow);
return () => {
window.removeEventListener("pageshow", handlePageShow);
};
}, []);
event.persisted 为 true,表示页面来自 BFCache。否则,应按普通重新加载或客户端导航的情况继续排查。
先修复实际的 hydration 差异
常见的差异来源有:
- 在 render 阶段读取
window、document或localStorage。 - 直接渲染
Date.now()、Math.random()或本地时区时间。 - 服务端和客户端取得的初始数据不同。
- 根据屏幕宽度、语言或浏览器能力生成不同的 DOM。
- HTML 标签嵌套无效,导致浏览器自动修正 DOM。
- 第三方组件在 hydration 前改动了页面结构。
以读取 localStorage 为例,应先保证服务端输出与客户端第一次渲染的内容相同,再在 effect 中更新:
"use client";
import { useEffect, useState } from "react";
export function ThemeLabel() {
const [theme, setTheme] = useState<string | null>(null);
useEffect(() => {
setTheme(localStorage.getItem("theme") ?? "light");
}, []);
return <span>{theme ?? "加载中"}</span>;
}
服务端和客户端第一次都会渲染“加载中”,不会因为服务端无法读取 localStorage 而生成不同的 HTML。effect 执行后,只会更新这一小块内容。
缩小 client-only 边界
如果某个组件完全依赖浏览器 API,可以只关闭这个组件的 SSR,页面其他部分仍然照常渲染:
import dynamic from "next/dynamic";
const BrowserOnlyPanel = dynamic(
() => import("./BrowserOnlyPanel"),
{
ssr: false,
loading: () => <div aria-busy="true">加载中</div>,
}
);
export default function Page() {
return (
<main>
<h1>页面标题</h1>
<BrowserOnlyPanel />
</main>
);
}
这样可以保留页面主体稳定的服务端输出。ssr: false 的使用位置会受到 Next.js 路由模式和组件边界的限制,应放在允许使用 client-only 动态组件的客户端组件中。
用 useSyncExternalStore 判断客户端状态
需要在 hydration 后切换内容时,可以使用 React 提供的服务端快照机制:
"use client";
import {
type ReactNode,
useSyncExternalStore,
} from "react";
const subscribe = () => {
return () => {};
};
function useIsClient() {
return useSyncExternalStore(
subscribe,
() => true,
() => false
);
}
export function ClientOnly({
children,
fallback = null,
}: {
children: ReactNode;
fallback?: ReactNode;
}) {
const isClient = useIsClient();
return isClient ? children : fallback;
}
使用方式:
<ClientOnly fallback={<div aria-busy="true">加载中</div>}>
<BrowserDependentContent />
</ClientOnly>
getServerSnapshot 返回 false,因此服务端输出与 hydration 阶段的首次输出相同。客户端接管后,React 读取客户端快照,将状态更新为 true。这里不需要再用一次性的 passive effect 表示客户端已经接管。
即便使用这种方式,也要尽量保留稳定的页面框架,避免用 ClientOnly 包住整个路由内容。
确认是 BFCache 后如何处理
如果已经通过 pageshow.persisted 确认白屏只出现在 BFCache 恢复时,可以监听 pageshow,显式重建受影响的小型 client-only 子树:
"use client";
import {
type ReactNode,
useEffect,
useState,
} from "react";
export function RestorableClientOnly({
children,
fallback = null,
}: {
children: ReactNode;
fallback?: ReactNode;
}) {
const [ready, setReady] = useState(false);
const [restoreKey, setRestoreKey] = useState(0);
useEffect(() => {
setReady(true);
const handlePageShow = (event: PageTransitionEvent) => {
if (event.persisted) {
setReady(true);
setRestoreKey((value) => value + 1);
}
};
window.addEventListener("pageshow", handlePageShow);
return () => {
window.removeEventListener("pageshow", handlePageShow);
};
}, []);
if (!ready) {
return fallback;
}
return <div key={restoreKey}>{children}</div>;
}
key 改变后,对应子树会重新挂载,其中的本地状态也会丢失。因此,这种方法只适合处理确实存在恢复问题的小组件,不应包裹整个页面。
如果 pageshow 已经触发,但 React 状态更新没有产生任何效果,应继续检查控制台异常、第三方 DOM 操作以及根节点状态。此时问题已超出 hydration 条件判断的范围,反复切换 isHydrated 通常无法让失效的 React 根节点恢复工作。
suppressHydrationWarning 不能代替修复
对于时间、语言环境等确实无法在服务端保持一致的文本,可以在很小的范围内使用:
<time suppressHydrationWarning>
{new Date().toLocaleString()}
</time>
它只会抑制指定层级的警告,无法修复事件绑定、DOM 结构或状态恢复问题。不要把它加到页面根节点,以此隐藏所有 Hydration Error。
建议的处理顺序
先移除页面级的 return null,恢复稳定的服务端页面框架。然后根据控制台提示找到第一处服务端与客户端输出差异,把依赖浏览器的逻辑限制在具体组件内。
如果白屏仍然只在 Back 返回时出现,再用 pageshow.persisted 判断页面是否从 BFCache 恢复。确认后,可以对局部子树做恢复处理,并检查运行时异常。直接禁用 BFCache 或在返回时强制刷新页面只能作为临时措施,因为它们会丢失页面状态,也会延长返回页面时的等待时间。
备注:内容仅供参考。
