Next.js 14.1.0(SSG)移动端视图刷新时出现Hydration问题

问题场景 #

• 基于Next.js 14.1.0的SSG模式开发
• 桌面视图下页面运行、构建均正常
• 切换至移动端视图并刷新页面时，触发Hydration相关错误
• 已排除<p>、<button>嵌套在其他<p>标签的DOM结构问题，怀疑与react-device-detect依赖有关

控制台报错信息 #

• Warning: Prop "href" did not match. Server: "http://localhost:3000" Client: "http://localhost:3000/"
• Warning: An error occurred during hydration. The server HTML was replaced with client content in <div>.
• Uncaught Error: Hydration failed because the initial UI does not match what was rendered on the server.
• Uncaught Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.

问题根源分析 #

1. URL尾部斜杠不一致：服务端与客户端渲染的href存在尾部斜杠差异，这是因为设备检测逻辑在服务端和客户端的执行环境不同，导致路由/链接的渲染输出不一致。
2. 服务端与客户端UI不匹配：react-device-detect依赖浏览器API，服务端渲染时无法获取真实设备信息，默认渲染桌面端UI；而客户端刷新时检测到移动端，渲染移动端UI，两者DOM结构差异触发Hydration失败。

解决方案 #

1. 改用Next.js内置设备检测逻辑 #

避免依赖第三方库，使用客户端组件结合useEffect执行设备检测，确保仅在客户端渲染时判断设备：

'use client';
import { useEffect, useState } from 'react';

const DeviceAwareContent = () => {
  const [isMobile, setIsMobile] = useState(false);
  const MOBILE_BREAKPOINT = 768;

  useEffect(() => {
    const checkDevice = () => setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
    // 初始化检测
    checkDevice();
    // 监听窗口大小变化
    window.addEventListener('resize', checkDevice);
    return () => window.removeEventListener('resize', checkDevice);
  }, []);

  return isMobile ? <div>移动端专属内容</div> : <div>桌面端内容</div>;
};

export default DeviceAwareContent;

2. 为设备相关组件添加Suspense边界 #

将依赖react-device-detect的组件包裹在Suspense中，让客户端单独渲染该部分内容，避免整个页面Hydration失败：

import { Suspense } from 'react';
import MobileOnlyContent from './MobileOnlyContent'; // 包含react-device-detect的组件

const Page = () => {
  return (
    <div className="page-container">
      {/* 服务端渲染一致的公共内容 */}
      <Suspense fallback={<div>加载中...</div>}>
        <MobileOnlyContent />
      </Suspense>
    </div>
  );
};

export default Page;

3. 统一URL尾部斜杠配置 #

在next.config.js中指定trailingSlash配置，确保服务端与客户端的URL格式一致：

/** @type {import('next').NextConfig} */
const nextConfig = {
  trailingSlash: true, // 设为false则统一移除尾部斜杠，根据需求选择
};

module.exports = nextConfig;

4. 修正react-device-detect的使用方式 #

若必须使用该库，将组件标记为客户端组件，并在useEffect中初始化设备状态，避免服务端渲染时执行检测：

'use client';
import { isMobile } from 'react-device-detect';
import { useEffect, useState } from 'react';

const MobileContent = () => {
  const [deviceIsMobile, setDeviceIsMobile] = useState(false);

  useEffect(() => {
    setDeviceIsMobile(isMobile);
  }, []);

  return deviceIsMobile ? <div>移动端内容</div> : null;
};

export default MobileContent;

内容的提问来源于stack exchange，提问作者Nikita