错误处理类

函数	用途	显示错误页面	返回值
`useError`	获取全局错误	❌	`Ref<Error>`
`createError`	创建错误对象	❌	`H3Error`
`showError`	显示全屏错误页面	✅	`undefined`
`clearError`	清除错误并恢复	—	`undefined`

useError

获取当前全局错误的引用。

const error = useError()

if (error.value) {
  console.log(error.value.statusCode)      // 404
  console.log(error.value.statusMessage)   // 'Not Found'
  console.log(error.value.message)         // 详细消息
  console.log(error.value.data)            // 附加数据
}

useError 的用途

在布局中检查是否有全局错误
根据错误类型显示不同的 UI
判断应用是否处于错误状态

createError

创建错误对象，不会自动显示错误页面。需要 throw 才能触发。

// 完整形式
const error = createError({
  statusCode: 404,
  statusMessage: 'Not Found',   // 简短的 HTTP 状态描述
  message: '页面不存在',         // 详细的错误描述（可包含中文）
  fatal: false,                 // 致命错误（无法通过 clearError 恢复）
  data: { field: 'id' },        // 附加数据
})

// 简写
throw createError('出错了')                     // 默认 500
throw createError({ statusCode: 404 })         // 只有状态码

服务端 vs 客户端

服务端：throw createError() → 返回 HTTP 错误响应
客户端：throw createError() → 需要自己 try/catch

TIP

详见错误创建与抛出完整教程

showError

显示全屏错误页面（error.vue）。

// 完整形式
showError({
  statusCode: 403,
  statusMessage: 'Forbidden',
  message: '无权限访问',
})

// 简写
showError('出错了')

showError vs createError

showError：创建 + 立即显示错误页面
createError：只创建错误对象，需要 throw 才触发

客户端主动显示错误用 showError

服务端抛出错误用 throw createError() 。

clearError

清除错误并恢复应用状态。

// 清除并跳转（推荐）
clearError({ redirect: '/' })

// 仅清除（尝试恢复之前的状态）
clearError()

clearError 的完整行为

清除全局错误状态
如果传了 redirect，导航到指定页面
如果没有 redirect，重新渲染之前的页面

INFO

️ 推荐总是带上 redirect 避免再次触发导致错误的页面

完整错误处理流程

// 1. 服务端抛出错误
throw createError({ statusCode: 404, statusMessage: 'Not Found', message: '资源不存在' })

// 2. 客户端显示错误页面
showError({ statusCode: 403, statusMessage: 'Forbidden', message: '无权限访问' })

// 3. 在 error.vue 中清除错误
clearError({ redirect: '/' })

TIP

详见错误处理章节完整教程

错误处理类 ​

useError ​

createError ​

showError ​

clearError ​

完整错误处理流程 ​