如何在Nuxt 3应用中将useFetch的错误传递至error.page

问题背景 #

开发Nuxt 3应用时，使用useFetch发起API请求，需要将请求返回的错误传递到error.page，展示对应的错误状态码和信息。

当前代码配置 #

api.ts 文件 #

import { useRuntimeConfig, useFetch } from 'nuxt3';

export const api = async (request: string, opts: any) => {
  const config = useRuntimeConfig();

  try {
    const fetch = await useFetch(request, {
      baseURL: config.public.API_BASE_URL,
      ...opts,
      headers: {
        Authorization: `Bearer ${getToken()}`,
      },
    });
    // 尝试过两种错误抛出方式
    if (fetch.error?.value) {
      throw new Error(
        `${fetch.error.value.statusCode} ${fetch.error.value.statusMessage}`
      );
    }

    return fetch;
  } catch (error) {
    throw error;
  }
};

error.vue 文件 #

<template>
  <NuxtLayout>
    <CommonLayoutUtilsErrorLayout
      :status-code="error.statusCode"
      :error-message="error.message"
    ></CommonLayoutUtilsErrorLayout>
  </NuxtLayout>
</template>

<script>
export default {
  props: {
    error: {
      type: Object,
      default: null,
    },
    errorMessage: String,
  },
  useHead() {
    return {
      title: `${this.error.statusCode} Error`,
    };
  },
};
</script>

已尝试的方法 #

• 方式一：抛出普通Error对象

if (fetch.error?.value) {
  throw new Error(
    `${fetch.error.value.statusCode} ${fetch.error.value.statusMessage}`
  );
}

• 方式二：使用createError抛出错误

if (fetch.error?.value) {
  // throw createError({ statusCode: fetch.error?.value?.statusCode, message: fetch.error?.value?.statusMessage })
  throw createError({ statusCode: 404, statusMessage: 'Page Not Found', fatal: true })
}

正确解决方案 #

1. 修正api.ts中的错误抛出逻辑 #

必须使用Nuxt提供的createError构造错误对象，而非普通Error，同时确保传递正确的状态码、信息并标记为致命错误：

import { useRuntimeConfig, useFetch, createError } from 'nuxt3';

export const api = async (request: string, opts: any) => {
  const config = useRuntimeConfig();

  const { data, error } = await useFetch(request, {
    baseURL: config.public.API_BASE_URL,
    ...opts,
    headers: {
      Authorization: `Bearer ${getToken()}`,
    },
  });

  if (error.value) {
    throw createError({
      statusCode: error.value.statusCode || 500,
      message: error.value.statusMessage || '请求失败',
      fatal: true // 标记为致命错误，触发error.page跳转
    });
  }

  return data;
};

2. 页面/组件中调用API #

在页面或组件中直接调用封装的api函数即可，无需额外捕获错误——createError抛出的错误会被Nuxt自动捕获并跳转至error.page：

<script setup>
import { api } from '~/utils/api';

// 直接调用，错误触发error.page
const data = await api('/your-api-path', { method: 'GET' });
</script>

3. 优化error.vue的接收逻辑 #

确保正确接收Nuxt传递的错误对象：

<template>
  <NuxtLayout>
    <CommonLayoutUtilsErrorLayout
      :status-code="error.statusCode"
      :error-message="error.message"
    ></CommonLayoutUtilsErrorLayout>
  </NuxtLayout>
</template>

<script setup>
const props = defineProps({
  error: {
    type: Object,
    required: true,
  },
});

useHead({
  title: `${props.error.statusCode} Error`,
});
</script>

关键注意事项 #

• 必须使用Nuxt的createError：普通Error对象无法触发Nuxt的error.page跳转逻辑。
• 务必设置fatal: true：该参数告知Nuxt这是需要展示错误页面的致命错误，尤其在服务端渲染场景下不可省略。
• 无需额外嵌套try/catch：useFetch的错误已被捕获到error.value中，直接判断抛出即可。

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