错误类

createError

创建 Nuxt 错误对象，可在服务端和客户端使用。

function createError(
  err: string | {
    statusCode: number       // HTTP 状态码
    statusMessage?: string   // 状态消息（短描述）
    message?: string         // 详细信息
    fatal?: boolean          // 是否致命错误（触发错误页面）
    data?: any               // 附加数据
    cause?: Error            // 原始错误
  }
): H3Error

// 完整形式
throw createError({
  statusCode: 404,
  statusMessage: 'Not Found',
  message: '用户不存在',
  fatal: false,
  data: { userId: 123 },
})

// 简写
throw createError('出错了')
throw createError({ statusCode: 404 })

服务端使用

// server/api/user/[id].ts
export default defineEventHandler((event) => {
  const id = getRouterParam(event, 'id')

  if (!id || isNaN(Number(id))) {
    throw createError({
      statusCode: 400,
      statusMessage: 'Bad Request',
      message: 'Invalid user ID',
    })
  }

  const user = await findUser(Number(id))
  if (!user) {
    throw createError({
      statusCode: 404,
      statusMessage: 'Not Found',
      message: `用户 ${id} 不存在`,
    })
  }

  return user
})

TIP

在服务端抛出 createError Nitro 会自动设置对应的 HTTP 状态码

INFO

️ statusMessage 应使用简短的 HTTP 状态描述（如 "Bad Request"、"Not Found"）不要放中文或长文本。详细的错误描述应放在 message 中，否则会收到 h3 警告

showError

显示全屏错误页面（不抛出异常，适合在组件中使用）。

function showError(
  err: string | {
    statusCode: number
    statusMessage?: string
    message?: string
    data?: any
  }
): void

showError({ statusCode: 403, statusMessage: 'Forbidden', message: '无权限访问' })
showError('出错了')

在组件中使用

vue

<script setup>
const { data, error } = await useFetch('/api/data')

if (error.value) {
  showError({
    statusCode: error.value.statusCode,
    statusMessage: error.value.statusMessage,
    message: error.value.message,
  })
}
</script>

INFO

️ showError 与 createError 的区别

createError 创建错误对象，需要 throw 抛出
showError 直接显示错误页面，适合异步回调中使用

clearError

清除错误并恢复应用。

function clearError(options?: {
  redirect?: string  // 清除后跳转的路径
}): Promise<void>

clearError({ redirect: '/' })  // 清除并跳转首页
clearError()                     // 仅清除，不跳转

在错误页面中使用

vue

<!-- app/error-500.vue -->
<template>
  <div>
    <h1>服务器错误</h1>
    <button @click="handleClear">返回首页</button>
  </div>
</template>

<script setup>
const props = defineProps<{ error: { statusCode: number } }>()

async function handleClear() {
  await clearError({ redirect: '/' })
}
</script>

TIP

clearError 会重置 Nuxt 的错误状态并可选地导航到指定页面

错误类 ​

createError ​

服务端使用 ​

showError ​

在组件中使用 ​

clearError ​

在错误页面中使用 ​

错误类