Nuxt 3服务端渲染报错window is not defined是什么原因？怎么修复？

先确认报错现象

在 Nuxt 3 服务端渲染过程中，如果遇到 ReferenceError: window is not defined，通常发生在页面预渲染或构建阶段。报错堆栈会指向某个具体文件，比如 .vue 组件的顶层、composable 的全局区域或 plugin 的 inject 函数内。先定位报错文件的行号，再看代码是否在 onMounted 或 onBeforeMount 生命周期之外直接引用了浏览器 API。

最直接的修复方式是将浏览器 API 的调用放入 onMounted (Vue3) 或 mounted (Vue2) 生命周期中，因为这些钩子只在客户端执行。例如：`onMounted(() => { console.log(window.innerWidth) })`。对于需要早期初始化的逻辑，可以使用 `if (process.client)` 或 `if (import.meta.client)` 包裹代码，但需注意前者在构建时会被保留，后者是 Nuxt 3 推荐的编译时标志。

全局搜索代码中的 `window.`、`document.`、`location.`、`navigator.` 等关键字，排查所有 .vue 文件和 composables 中是否有顶层引用。特别是 store 中的 actions、中间件（middleware）以及 plugins 中的 inject 函数，因为它们可能在服务端执行。如果项目使用了 Nuxt 3 的 `useHead` 或 `useSeoMeta`，这些组合式函数本身是安全的，但回调里不要写浏览器 API。

Nuxt 3服务端渲染报错window is not defined是什么原因？怎么修复？

容易踩的坑

很多人习惯用 typeof window !== 'undefined' 做判断，但这种方式在 modern build 优化下可能不可靠。Nuxt 3 的编译过程可能静态分析该判断，导致条件分支被死代码消除。更隐蔽的是第三方库在 setup 中直接调用 document.getElementById 或 navigator.userAgent，这些都会在服务端抛出错误。另外，useRuntimeConfig 本身是安全的，但如果在 app.vue 的顶层写 console.log(window) 就会立即炸掉。

代码检查入手方向

全局搜索代码中的 window.、document.、location.、navigator. 等关键字，排查所有 .vue 文件和 composables 中是否有顶层引用。特别是 store 中的 actions、中间件（middleware）以及 plugins 中的 inject 函数，因为它们可能在服务端执行。如果项目使用了 Nuxt 3 的 useHead 或 useSeoMeta，这些组合式函数本身是安全的，但回调里不要写浏览器 API。先列一个清单，把命中位置逐项标记出来，再逐个决定是移到生命周期内还是用 import.meta.client 包裹。

验证与回滚

修复完成后，运行 npm run build 并生成静态文件（npx nuxi generate）或使用 node .output/server/index.mjs 启动生产服务。用浏览器访问页面时，打开开发者工具的网络面板，确认服务端响应没有出现 500 错误。如果发现内容闪烁或客户端水合警告，说明 <ClientOnly> 内部使用了异步数据请求，需要把数据请求提到外层。回滚时，直接利用 Git 恢复上一次提交，并重新构建。

后续维护注意

不要依赖 typeof window !== 'undefined' 作为唯一判断条件，因为在 modern build 下某些优化可能导致该检查失效。更稳妥的做法是使用 Nuxt 3 提供的 useClientOnly 组合式函数，或直接用 <ClientOnly> 组件包裹有浏览器依赖的 DOM 结构。注意 <ClientOnly> 内部不能使用服务端渲染的异步数据请求（如 useAsyncData），否则水合时会出现内容闪烁。另外，养成在 composable 中写 if (import.meta.client) 前置检查的习惯，可以大幅减少此类报错。在 Code Review 阶段，重点审查 setup 函数中的全局对象引用，避免新人直接写 window 而不加保护。

笙亿网络策划