使用Next.js导出静态HTML异常：无CSS/JS及Hydration报错

问题概述 #

执行next build && next export生成out文件夹后，直接打开HTML仅显示纯文本内容（CSS/JS未加载），同时出现以下React Hydration错误：

Hydration failed because the initial UI does not match what was rendered on the server.
There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.

当前next.config.js配置：

// /** @type {import('next').NextConfig} */
// const nextConfig = {
//   reactStrictMode: true,
//   swcMinify: true,
// }

// module.exports = nextConfig

module.exports = {
 assetPrefix: './',
 images: {
   unoptimized: true
 }
}

1. 解决CSS/JS资源加载失败问题 #

错误原因 #

直接双击本地HTML文件时，浏览器使用file://协议，会限制相对路径资源的加载；同时Next.js 13+版本的静态导出配置有更新，旧命令和配置组合可能导致资源生成异常。

修复步骤 #

调整Next.js配置（适配13+版本）

修改next.config.js为：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // 13+版本推荐的静态导出配置，替代单独的next export命令
  assetPrefix: './',
  images: {
    unoptimized: true,
  },
}

module.exports = nextConfig

更新build命令

修改package.json中的build命令，无需再单独执行next export：

"build": "next build"

正确访问静态文件

不要直接双击HTML文件，用本地服务器托管out文件夹：

# 安装serve（如果没装过）
npm install -g serve
# 启动服务
serve out

然后访问http://localhost:3000即可正常加载CSS/JS。

2. 解决Hydration失败错误 #

常见原因及修复 #

（1）使用了客户端专属API

直接在组件顶层使用window、document等仅在浏览器环境存在的对象，会导致服务端渲染时无法找到这些对象，引发UI不匹配。

修复示例：

import { useEffect, useState } from 'react'

function MyComponent() {
  const [windowWidth, setWindowWidth] = useState(0)

  useEffect(() => {
    // 仅在客户端执行
    setWindowWidth(window.innerWidth)
  }, [])

  return <div>窗口宽度：{windowWidth}</div>
}

（2）服务端与客户端初始状态不一致

比如依赖客户端状态初始化的内容，服务端渲染时无法获取，导致初始UI差异。

修复示例：用Suspense包裹客户端专属组件

import { Suspense } from 'react'

// 包含客户端专属逻辑的组件
function ClientComponent() {
  return <div>{window.location.href}</div>
}

function Page() {
  return (
    <Suspense fallback={<div>加载中...</div>}>
      <ClientComponent />
    </Suspense>
  )
}

（3）日期/时区差异

服务端和客户端时区不同，导致渲染的日期字符串不一致。

修复示例：在客户端渲染日期

import { useEffect, useState } from 'react'

function DateDisplay() {
  const [currentDate, setCurrentDate] = useState('')

  useEffect(() => {
    setCurrentDate(new Date().toLocaleString())
  }, [])

  return <div>当前时间：{currentDate}</div>
}

（4）React Strict Mode触发的重复渲染

开启reactStrictMode: true时，组件会被渲染两次，可能暴露隐藏的不匹配问题。可以暂时关闭排查：

const nextConfig = {
  output: 'export',
  assetPrefix: './',
  images: {
    unoptimized: true,
  },
  reactStrictMode: false, // 暂时关闭排查，找到问题后再开启
}

验证流程 #

1. 删除旧的out文件夹
2. 执行npm run build重新生成静态文件
3. 用serve out启动本地服务器访问
4. 检查控制台是否还有Hydration错误，逐步排查客户端代码

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