Nuxt3 SSR数据获取异常：初始加载返回HTML而非数据求助

核心原因分析 #

你遇到的问题本质是服务端渲染阶段API请求未正确命中目标接口，反而返回了Nuxt自身的页面HTML。热更新正常是因为客户端环境下API配置/请求路径正确，而服务端环境存在配置或路径错误。

常见触发场景：

• public.API_URL在服务端未正确配置，导致useFetch默认请求Nuxt服务器自身，返回404/错误页面的HTML
• 服务端无法访问目标API（比如本地API未启动、内网地址服务端不可达）
• 封装useApi时参数合并或key设置不当，导致请求异常

排查与解决步骤 #

1. 确认API配置的正确性 #

检查nuxt.config.ts中的runtimeConfig配置，确保服务端和客户端的public.API_URL都指向正确的API地址：

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      API_URL: process.env.NUXT_PUBLIC_API_URL || 'https://your-real-api.com'
    }
  }
})

• 本地开发时，若API运行在http://localhost:3001，则设置NUXT_PUBLIC_API_URL=http://localhost:3001
• 注意：服务端渲染时，请求是从Nuxt服务器发出的，不能用客户端的相对路径（比如/api），除非你配置了Nuxt代理

2. 排查请求错误信息 #

在组件中添加错误和状态日志，查看服务端渲染时的请求状态：

// component.vue
const { get } = useApi();
const { data: jobs, error, status } = await get<IJob[]>('/jobs/');

// 服务端日志会输出这些信息，帮助定位问题
console.log('请求状态:', status.value);
console.log('错误信息:', error.value);

如果输出状态码是404/500，说明请求地址错误或API服务异常，此时可以查看useFetch实际请求的完整URL（在Nuxt服务端日志或API服务器日志中查看）。

3. 修正useApi封装的问题 #

你的useApi封装存在两个潜在问题：

• 参数合并逻辑错误：原代码将params作为独立参数传入，但useFetch的参数是url和options，需要合并options
• key设置不唯一：仅用url.toString()当key，若不同参数请求同一接口会缓存冲突

修正后的useApi：

// useApi.ts
import { useFetch, UseFetchOptions } from 'nuxt/app';

export default function useApi() {
  const config = useRuntimeConfig();

  const get = <T>(url: string, options?: Omit<UseFetchOptions<T>, 'baseURL'>) => {
    // 生成唯一key，避免不同参数的请求缓存冲突
    const key = `${url}_${JSON.stringify(options?.params || {})}`;
    
    return useFetch<T>(url, {
      baseURL: config.public.API_URL,
      key,
      // 合并传入的options，优先级高于默认配置
      ...options,
    });
  };

  return { get };
}

4. 验证服务端API可达性 #

确保服务端渲染时Nuxt服务器能访问到目标API：

• 本地开发时，若API运行在本地，确认Nuxt服务器所在环境能访问该地址（比如不要用127.0.0.1而用localhost，或检查防火墙）
• 生产环境中，确认API地址是公网可达的，或配置了内网访问权限

额外提示 #

若使用Nuxt代理（nitro.proxy），需在nuxt.config.ts中配置代理规则，此时客户端用相对路径，服务端会自动转发请求：

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    proxy: {
      '/api/': {
        target: 'https://your-real-api.com',
        changeOrigin: true
      }
    }
  },
  runtimeConfig: {
    public: {
      API_URL: '/api/' // 客户端用相对路径，服务端通过代理转发
    }
  }
})

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