Nuxt useFetch SSR返回null但客户端正常的问题求助

问题根源分析 #

1. SSR状态同步机制被破坏：你的GetApi用额外Promise包裹useFetch结果，并直接取res.data.value，导致Nuxt无法跟踪SSR异步状态，服务端数据无法序列化到客户端，客户端只能拿到null。
2. 超时配置无效：将timeout放在headers中是错误的，useFetch的timeout是顶级配置项，不属于请求头，之前的超时设置完全没生效，慢API在SSR时可能未完成响应就被渲染。
3. onMounted调用逻辑错误：onMounted是客户端专属钩子，你的封装未正确处理客户端环境下的useFetch初始化，加上Promise包装的异步流程问题，导致返回空值。

修复后的API封装代码 #

// Core API wrapper
export const apiCore = (url, options = {}) => {
  const runtimeConfig = useRuntimeConfig();
  const baseURL = runtimeConfig.public.baseURL;

  return useFetch(url, {
    baseURL,
    timeout: 20000, // 正确配置超时：顶级配置项
    onRequest({ options: reqOptions }) {
      // 合并请求头，保留useFetch默认头（如Accept）
      reqOptions.headers = {
        ...reqOptions.headers,
        ...options.headers,
      };
    },
    onResponse({ response }) {
      // 统一返回响应数据，简化上层调用
      return response._data;
    },
    onResponseError({ response, error }) {
      // 统一错误处理，抛出可识别的错误
      console.error('API请求失败:', response?.status, error);
      throw new Error(response?._data?.message || '网络请求异常');
    },
    ...options, // 允许传入配置覆盖默认值
  });
};

// GET请求封装：无需额外Promise包装
export const GetApi = (url, options = {}) => {
  return apiCore(url, {
    method: 'GET',
    ...options,
  });
};

数据获取函数与组件用法 #

数据获取函数 #

// Data fetching function
export const getData = (start_time, end_time) => {
  const defaultStartTime = new Date().getTime() - 86400000;
  const defaultEndTime = new Date().getTime();

  return GetApi('/api/data/1/10', {
    params: {
      start_time: start_time || defaultStartTime,
      end_time: end_time || defaultEndTime,
    },
  });
};

组件中正确使用 #

<script setup>
import { getData } from '~/api/getData.js';

// SSR/客户端通用：直接解构useFetch返回的响应对象，Nuxt自动同步状态
const { data: res, pending, error } = await getData();

// 监听数据变化
watch(res, (newVal) => {
  console.log('获取到数据:', newVal);
});

// 仅客户端调用（onMounted）
onMounted(async () => {
  const { data: clientRes } = await getData();
  console.log('客户端数据:', clientRes.value);
});
</script>

针对疑问的解答 #

1. 是否与Nuxt SSR行为相关？
   是。Nuxt通过useFetch/useAsyncData的ref对象跟踪SSR异步状态，将服务端数据序列化到客户端进行hydration。你的封装破坏了这个机制，导致状态同步失败。

2. 如何正确配置超时？
   将timeout作为useFetch的顶级配置项传入（如修复后的代码），不要放在headers中。同时可以配合onResponseError处理超时导致的错误。

3. 如何确保SSR与客户端数据一致？

• 不要手动包裹Promise或直接取data.value，直接返回useFetch的结果；
• 在组件的setup阶段（或<script setup>）直接await API调用，让Nuxt自动处理状态同步；
• 避免在SSR中使用客户端专属API，确保服务端能正常访问目标API。

额外建议 #

• 可以使用Nuxt原生的$fetch替代手动封装useFetch，$fetch与Nuxt的SSR机制兼容性更好；
• 调试时可在服务端打印data.value，确认服务端是否正确获取数据，再排查客户端hydration问题；
• 如果需要缓存数据，可给useFetch或useAsyncData添加唯一的key参数。

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