Next.js部署阶段出现预渲染错误，求解决方案及原因

错误原因 #

• /about页面预渲染失败：多半是页面里用了window、document这类客户端专属API，或者异步数据获取没处理好，导致静态生成/服务器渲染阶段执行出错。
• /404页面useSearchParams()报错：Next.js 13+ App Router里，useSearchParams是客户端钩子，服务端预渲染（包括404页面的预渲染）时不能直接用，必须套在Suspense边界里，让React在客户端渲染这部分内容。

修复方法 #

一、解决/about页面预渲染错误 #

1. 检查About页面代码，定位客户端API的使用：

   • 如果直接写了window/document相关代码，用useEffect包裹，确保只在客户端执行：

     import { useEffect, useState } from 'react';
     
     export default function About() {
       const [windowWidth, setWindowWidth] = useState(0);
     
       useEffect(() => {
         setWindowWidth(window.innerWidth);
       }, []);
     
       return <div>窗口宽度：{windowWidth}</div>;
     }
     

   • 如果是异步数据获取，要么用getStaticProps（静态生成）或getServerSideProps（服务器渲染），要么在客户端用useEffect+fetch，同时配合Suspense处理加载状态。

2. 本地执行npm run build，查看具体错误信息，精准定位代码里的问题（比如未处理的异步依赖、客户端API提前执行）。

二、解决/404页面useSearchParams的Suspense问题 #

1. 把404页面里使用useSearchParams的部分抽成独立子组件，再用Suspense包裹：

   import { Suspense } from 'react';
   import { useSearchParams } from 'next/navigation';
   
   // 单独封装使用useSearchParams的组件
   function SearchParamsContent() {
     const searchParams = useSearchParams();
     const query = searchParams.get('q');
   
     return <div>搜索关键词：{query}</div>;
   }
   
   export default function NotFound() {
     return (
       <div>
         <h1>404 - 页面未找到</h1>
         {/* 用Suspense包裹，添加加载占位符 */}
         <Suspense fallback={<div>加载中...</div>}>
           <SearchParamsContent />
         </Suspense>
       </div>
     );
   }
   

2. 注意事项：
   • 不要在RootLayout中直接使用useSearchParams，如果布局需要用到搜索参数，同样抽成子组件并套上Suspense。
   • 确保Suspense边界处于客户端组件层级中，避免服务端渲染阶段触发客户端钩子执行。

验证步骤 #

• 本地执行npm run build，确认预渲染错误消失。
• 部署前先启动生产环境服务（npm run start），测试/about和/404页面是否正常加载。

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