Nuxt3开启SSR后，utils目录调用useRuntimeConfig报实例不可用

错误原因 #

• useRuntimeConfig 是Nuxt3的组合式API函数，必须在Nuxt提供的上下文环境中调用（比如组件、页面、插件、composables的setup函数内）。
• 你在utils/ApiBridge.js这个普通JS模块中直接调用useRuntimeConfig，在SSR模式下，服务器端会直接执行这个模块的代码，此时没有初始化Nuxt实例，因此抛出“Nuxt instance unavailable”错误。

为什么关闭SSR时正常？ #

当ssr: false时，项目以SPA模式运行，所有代码仅在浏览器端执行。此时Nuxt实例已经初始化完成，上下文环境存在，useRuntimeConfig可以正常获取配置，所以不会报错。

当前实现方式的问题 #

直接在非上下文环境的普通JS模块中使用Nuxt的组合式API，违反了Nuxt3的API使用规则，这种写法在SSR场景下必然出错。

修复方案 #

推荐两种标准实现方式：

方案一：将API桥改为Composable #

将文件移至composables/useApiBridge.js（Nuxt会自动识别composables目录，无需手动导入）：

import axios from "axios";

export const useApiBridge = () => {
  // 此处处于Nuxt上下文环境，可安全调用useRuntimeConfig
  const runtimeConfig = useRuntimeConfig();

  const api = axios.create({
    baseURL: runtimeConfig.public.API_BASE_URL,
    withCredentials: true,
  });

  return {
    login: (info) => api.post('/login', info),
    register: (info) => api.post('/register', info)
    // 其他接口方法...
  };
};

在组件/页面中使用：

const apiBridge = useApiBridge();
// 调用示例：apiBridge.login({ username: 'xxx', password: 'xxx' })

方案二：通过Nuxt插件注入API实例 #

创建plugins/axios.js，利用Nuxt插件的上下文环境配置axios：

import axios from "axios";

export default defineNuxtPlugin(() => {
  const runtimeConfig = useRuntimeConfig();

  const api = axios.create({
    baseURL: runtimeConfig.public.API_BASE_URL,
    withCredentials: true,
  });

  // 可选：添加请求/响应拦截器
  // api.interceptors.request.use(...)
  // api.interceptors.response.use(...)

  // 封装API方法
  const apiBridge = {
    login: (info) => api.post('/login', info),
    register: (info) => api.post('/register', info)
    // 其他接口方法...
  };

  return {
    provide: {
      api: apiBridge
    }
  };
});

在组件/页面中使用：

const { $api } = useNuxtApp();
// 调用示例：$api.login({ username: 'xxx', password: 'xxx' })

关于自动导入的疑问 #

和自动导入无关。自动导入仅帮你省去手动导入useRuntimeConfig等函数的步骤，但无法改变“组合式API必须在Nuxt上下文环境中调用”的规则。

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