Next.js构建报错：/404页面useSearchParams()需包裹Suspense边界

报错信息 #

⨯ useSearchParams() should be wrapped in a suspense boundary at page "/404". Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout
    at a (C:\Users\USER\Desktop\dock-fe\.next\server\chunks\203.js:3:13936)
    at d (C:\Users\USER\Desktop\dock-fe\.next\server\chunks\203.js:5:30727)
    at p (C:\Users\USER\Desktop\dock-fe\.next\server\chunks\403.js:1:10402)
    at nF (C:\Users\USER\Desktop\dock-fe\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:76:46843)
    ...
    at nX (C:\Users\USER\Desktop\dock-fe\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:76:69876)
Error occurred prerendering page "/_not-found". Read more: https://nextjs.org/docs/messages/prerender-error
Export encountered an error on /_not-found/page: /_not-found, exiting the build.
⨯ Next.js build worker exited with code: 1 and signal: null

已尝试的无效操作 #

• 为自定义错误页面添加Suspense边界，无效；
• 删除自定义错误页面，无效；
• 删除所有与自定义错误页面相关的代码，无效；
• 删除.next目录后重新构建，无效；
• 为所有含useSearchParams()的代码添加Suspense边界，无效；
• 为项目顶级布局添加Suspense边界，无效。

针对性解决方法 #

1. 检查全局组件的隐性调用
   全局引入的组件（如导航栏、全局弹窗）可能在404页面渲染时被加载，且内部调用了useSearchParams()。找到这类组件，将其包裹在Suspense中，或改用useParams()（仅需路径参数时），或在组件内判断当前页面是否为404，跳过查询参数相关逻辑。

2. 强制404页面渲染模式
   在404页面代码顶部添加渲染模式声明：

   • 若无需动态数据，用export const dynamic = 'force-static'强制静态生成；
   • 若必须保留动态逻辑，用export const dynamic = 'force-dynamic'跳过预渲染，避免构建时的Suspense校验。

3. 排查第三方依赖
   部分第三方UI库或工具可能内部使用useSearchParams()且未处理Suspense边界。检查全局或404页面加载的第三方组件，替换为兼容版本，或直接将第三方组件包裹在Suspense中。

4. 调整Next.js版本
   旧版Next.js在App Router模式下对404页面的Suspense处理存在bug，尝试升级到最新稳定版，或回退到13.4.x等已知无此问题的版本。

5. 创建极简_not-found页面
   在app/_not-found/page.js中编写无动态逻辑的极简404页面，确保预渲染顺利完成：

   export default function NotFound() {
     return <div>页面未找到</div>
   }
   

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