执行npm run build构建Next.js应用时预渲染页面报错

执行npm run build生成生产构建包时，/actions/user页面预渲染失败，报错信息如下：

Error occurred prerendering page "/actions/user". Read more: https://nextjs.org/docs/messages/prerender-error
Error: 压缩后的React错误 #31；查看完整信息请使用非压缩的开发环境，错误涉及的对象包含以下键：{data, error, loading, mutate, isValidating}
   
    at a.b.read (D:\Portfolio\portfolio\portfolioapp\node_modules\react-dom\cjs\react-dom-server.node.production.min.js:41:83)
    at Object.exports.renderToString (D:\Portfolio\portfolio\portfolioapp\node_modules\react-dom\cjs\react-dom-server.node.production.min.js:52:138)       
    at Object.renderPage (D:\Portfolio\portfolio\portfolioapp\node_modules\next\dist\server\render.js:751:45)
    at Object.defaultGetInitialProps (D:\Portfolio\portfolio\portfolioapp\node_modules\next\dist\server\render.js:389:51)
    at Function.getInitialProps (D:\Portfolio\portfolio\portfolioapp\.next\server\pages\_document.js:502:20)
    at Object.loadGetInitialProps (D:\Portfolio\portfolio\portfolioapp\node_modules\next\dist\shared\lib\utils.js:69:29)

问题根源 #

这个错误是因为服务端预渲染（SSG/SSR）过程中，页面组件使用了无法在服务端序列化或仅能在客户端运行的对象——从报错里的对象键（mutate是函数，属于不可序列化内容）来看，大概率是用了SWR/React Query这类数据请求库的hooks，且没有处理服务端与客户端的渲染差异。

解决步骤 #

• 定位代码问题：打开/pages/actions/user页面，查找使用SWR/React Query的代码块，确认是否在组件渲染阶段直接调用了这些hooks，且未做客户端判断。
• 改用服务端数据获取：如果页面是静态生成（SSG），用getStaticProps在构建时获取数据，将数据作为props传入页面组件，替换组件内的hooks请求。
• 客户端条件渲染：必须在客户端使用hooks的话，用typeof window !== 'undefined'包裹hooks调用，或者用useEffect延迟执行，确保只在客户端初始化：

  import useSWR from 'swr';
  import { useState, useEffect } from 'react';
  
  function UserPage() {
    const [userData, setUserData] = useState(null);
    const [isLoading, setIsLoading] = useState(true);
  
    useEffect(() => {
      const fetcher = async (url) => {
        const res = await fetch(url);
        return res.json();
      };
  
      const { data } = useSWR('/api/user', fetcher);
      setUserData(data);
      setIsLoading(false);
    }, []);
  
    if (isLoading) return <div>加载中...</div>;
    return <div>{userData?.name}</div>;
  }
  

• 查看完整错误：运行npm run dev启动开发环境，此时会显示非压缩的完整错误信息，能直接定位到出错的组件和代码行，更高效排查。
• 检查客户端API访问：确认页面中没有在服务端渲染时访问window、document这类客户端专属API，这类代码同样需要用客户端判断包裹。

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