PAYATHON 2026

条件渲染解决 Hydration Error 后 Back button 返回白屏

排障赵师傅

结论

不建议用页面级的 if (!isHydrated) return null 长期处理 Hydration Error。这种写法让服务端和客户端首次渲染时都不输出内容,暂时避开了差异,却会带来一段白屏时间,也失去了 SSR 原本的作用。

可以按下面的方式处理:

  1. 定位并修复服务端与客户端的实际输出差异。
  2. 只隔离依赖浏览器环境的局部组件,让页面其他部分正常渲染。
  3. 必须判断客户端环境时,优先使用 useSyncExternalStore,或者确保服务端和客户端首次渲染相同的占位内容。
  4. 确认问题与浏览器的 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 或在返回时强制刷新页面只能作为临时措施,因为它们会丢失页面状态,也会延长返回页面时的等待时间。

备注:内容仅供参考。