Nuxt 3 useFetch 服务端请求失败导致白屏，通常是因为未捕获异步错误或服务端渲染上下文丢失。最推荐的处理方向是在组件 setup 顶层同步调用 useFetch 并配合 error 属性判断，避免在异步函数内部直接调用。

快速处理思路

针对白屏问题，不需要复杂命令，重点在于代码结构调整和错误兜底。

1. 将 useFetch 调用从异步函数内部移至 script setup 顶层作用域。
2. 在模板中增加 v-if 判断 error 状态，防止空数据导致渲染崩溃。
3. 检查服务端启动日志，确认是否有 SSR 上下文相关的报错信息。

为什么会这样

白屏的根本原因是服务端渲染流程被阻断或客户端水合失败。useFetch 等组合式函数依赖特定的 Nuxt 实例上下文，该上下文仅在 setup 函数、插件或中间件的同步执行阶段有效。如果在异步函数内部调用 useFetch，执行 tick 结束后上下文会被清空，导致“Nuxt instance unavailable”错误，进而引发服务端渲染中断返回空 HTML。此外，若未对请求错误进行捕获，服务端抛出未处理异常也会直接导致页面渲染终止。

分步处理

按照以下顺序修复代码，确保 SSR 流程完整。

1. 调整调用位置

确保 useFetch 在 script setup 顶层直接调用，不要封装进普通 async 函数。错误写法是将请求逻辑放入自定义异步函数并在 setup 中 await，正确写法是直接在 setup 中解构。

<script setup>
// 正确：顶层调用
const { data, error } = await useFetch('/api/data')
</script>

2. 增加错误兜底

在模板中判断 error 状态，避免访问 undefined 数据导致白屏。使用 status 属性区分加载、成功和失败状态。

<template>
  <div v-if="status === 'pending'">加载中</div>
  <div v-else-if="status === 'error'">错误：{{ error.message }}</div>
  <div v-else>{{ data }}</div>
</template>

3. 检查 SSR 兼容性

确认请求逻辑中没有访问 window、document 等浏览器专属对象。如果在 onRequest 钩子中需要处理 Cookie，使用 useRequestHeaders 转发头部，不要手动设置 Cookie 头部。

怎么验证是否生效

通过以下三个维度确认修复效果。

• 查看服务端日志：启动 Nuxt 后刷新页面，检查 Node 控制台是否还有“Nuxt instance unavailable”或 SSR render 错误。
• 检查页面源码：右键查看页面源代码，确认 HTML 中是否包含实际数据内容，而不是空骨架。
• 观察客户端控制台：刷新浏览器，确认没有 Hydration failed 或内容不匹配的警告。

常见坑

• 异步函数封装陷阱：将 useFetch 封装到独立 async 函数中会导致上下文丢失，报错通常出现在 Nuxt 3.10+ 版本。
• 参数监听触发：useFetch 默认监听参数变化，如果 body 传入引用类型对象，值变化会自动触发请求，建议关闭 watch 或传入字段值。
• 懒加载数据访问：使用 lazy: true 时，setup 阶段 data 可能为 undefined，直接访问会导致报错，需配合 watch 或模板空值保护。
• Cookie 头部失效：客户端跨域请求时手动设置 Cookie 头部会被浏览器阻止，服务端渲染时需通过 useRequestHeaders 转发。

常见问题

为什么刷新页面白屏但跳转正常？

因为刷新触发服务端渲染（SSR），而跳转通常是客户端渲染（CSR）。SSR 阶段如果 useFetch 报错或上下文丢失，会直接返回空 HTML 导致白屏。

useFetch 报错 Nuxt instance unavailable 怎么修？

将 useFetch 调用移出异步函数，确保在 setup 函数顶层同步执行，不要在 await 之后或 setTimeout 中调用。

如何防止请求失败导致整个页面崩溃？

利用 useFetch 返回的 error 对象在模板中做条件渲染，或者使用 try/catch 包裹异步逻辑，确保渲染流程不中断。

参考来源

• Nuxt3 中 useFetch 的 5 个常见坑点及解决方案 (附真实案例)
• 实战避坑指南:Nuxt3 useFetch 的正确使用姿势 (附常见错误修复)
• nuxt3 useFetch 刷新或首次进入报错 - Jade_g - 博客园
• SSR 白屏问题排查全流程：从渲染链路到问题定位思路_牛客网
• 解决 Nuxt.js 中 useFetch() pending 状态问题的完整指南