Nuxt 3 组合式 API 在服务端渲染中有哪些使用限制

Nuxt 3 组合式 API 依赖隐式上下文，在服务端渲染中必须在 setup 函数、插件或中间件内调用，否则会导致上下文丢失错误。避免在普通异步函数中直接封装 useFetch 或 useAsyncData，防止服务端渲染时数据预取失败。

先说结论：组合式 API 如 useFetch 必须在 Vue setup 上下文或 Nuxt 生命周期钩子中执行，不可在普通 async 函数中直接调用。

快速处理思路

若遇到上下文丢失报错，立即调整代码结构，确保组合式 API 调用位置符合 SSR 上下文要求。

错误写法：在普通 async 函数中直接 await useFetch。

正确写法：在<script setup>顶层直接调用，或通过自定义 composable 但在 setup 内触发。

<script setup>
// 正确：直接在 setup 中调用
const { data } = await useFetch('/api/data')
</script>

Nuxt 3 的组合式 API 依赖全局隐式上下文跟踪当前实例，该上下文在同一 JavaScript 运行 Tick 结束时被清理。

服务端渲染为防止跨请求状态污染，会在每个请求处理后重置上下文。若在普通异步函数中使用 await，函数执行暂停，控制权交还事件循环，导致上下文在恢复执行前已被清理，从而引发"Nuxt instance unavailable"错误。

按照以下步骤重构数据获取逻辑，确保服务端渲染正常。

1. 检查调用位置：确认 useFetch 或 useAsyncData 是否在<script setup>顶层、插件 setup 函数或中间件内。

2. 替换原生 Fetch：将原生 fetch 或 axios 请求替换为 Nuxt 内置的$fetch 配合 useAsyncData。

const { data, error } = await useAsyncData('key', () => $fetch('/api/user'))

3. 处理客户端 API：若代码涉及 window 或 document，使用 import.meta.client 或 onMounted 包裹。

if (import.meta.client) {
  console.log(window.location)
}

4. 统一模块语法：若混合使用 CommonJS 和 ESM 模块，通过@vitejs/plugin-legacy 插件兼容或统一转换为 ESM 语法。

通过日志检查和页面源码对比，确认服务端渲染是否成功。

1. 查看服务端日志：启动开发服务器，观察控制台是否出现"A composable that requires access to the Nuxt instance was called outside..."错误。

2. 检查页面源码：在浏览器右键查看页面源代码，确认关键数据是否已存在于 HTML 字符串中，而非仅存在于客户端 JS 加载后。

3. 监控 hydration 警告：打开浏览器控制台，确认没有"Hydration node mismatch"相关警告，表明服务端与客户端渲染内容一致。

开发过程中需警惕以下高频错误场景，避免影响生产环境稳定性。

1. 异步函数封装陷阱：不要将 useFetch 封装在独立 async 函数中并在 setup 外调用，这会导致上下文丢失。

2. 浏览器 API 直接调用：服务端环境不存在 window 和 document，直接调用会导致构建或运行时错误。

3. 依赖冲突：混合使用 axios (CommonJS) 和 pinia (ESM) 时可能遇到 require is not defined，需统一模块规范。

4. 节点版本不一致：确保服务器 Node.js 版本与本地开发版本匹配，Nuxt 3 通常要求 Node.js 16.x 或 18.x 以上。

因为 Nuxt 实例上下文在 await 暂停期间被清理，恢复执行时无法访问 Nuxt 实例。

使用 import.meta.client 判断环境，或将相关代码放入 onMounted 钩子中确保仅在客户端执行。

useFetch 是 useAsyncData 的封装，专门用于请求接口，自动处理 key 生成和去重，适合单个请求场景。