Next.js 14.0.2/14.0.3构建报错，14.0.1正常求排查方案

对应官方方案第3/4点的可能问题 #

第3点：服务器组件/预渲染阶段意外调用浏览器API #

14.0.2之后Next.js对App Router的服务器组件执行逻辑做了严格校验，你项目中可能存在以下情况：

• 多语言相关代码（比如读取document.cookie获取语言偏好、操作document.documentElement.lang）写在了未标记'use client'的组件顶层，14.0.1版本的预渲染逻辑可能跳过了这部分代码执行，14.0.2+则会完整执行，触发document未定义错误。
• 某些组件本该是客户端组件，却遗漏了'use client'指令，导致预渲染时执行了依赖浏览器API的代码。

第4点：第三方依赖在预渲染时访问浏览器API #

你的多语言依赖（如next-intl、i18next等）可能存在未适配Next.js 14.0.2+的情况：

• 依赖内部的初始化逻辑在预渲染阶段被提前触发，直接调用了document等浏览器API，而之前的14.0.1版本不会在预渲染时执行这部分逻辑。
• 依赖的版本过旧，未兼容Next.js 14.0.2+的预渲染流程变更。

14.0.2+版本导致构建失败的关键变更 #

Next.js 14.0.2和14.0.3主要在App Router预渲染与组件执行逻辑上做了调整：

• 预渲染代码执行更彻底：之前预渲染时可能被跳过的组件顶层代码，现在会完整执行，暴露了隐藏的浏览器API调用问题。
• 客户端组件边界校验更严格：静态分析能力升级，能精准检测到未标记'use client'却依赖浏览器API的组件，直接在build阶段报错。
• 国际化路由预渲染逻辑调整：针对App Router的多语言路由（如app/[lang]），预渲染流程的触发时机改变，导致你的多语言初始化代码提前执行，触发浏览器API调用。

排查修复建议 #

• 全局搜索document相关代码，确保所有调用都包裹在typeof window !== 'undefined'判断内，或仅出现在标记'use client'的组件的useEffect、事件回调中。
• 升级你的多语言依赖到最新版本，确认其适配Next.js 14.0.2+。
• 对怀疑的页面/组件添加dynamic: 'force-dynamic'配置，临时禁用预渲染，逐步定位错误来源。

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