错误处理

Nuxt 是一个全栈框架，这意味着在不同的上下文中可能会发生几种无法预防的用户运行时错误：

• 在 Vue 渲染生命周期中的错误（SSR 和 CSR）
• 服务器和客户端启动错误（SSR + CSR）
• 在 Nitro 服务器生命周期中的错误 (server/ 目录)
• 下载 JS 块时的错误

Vue 错误

您可以使用 onErrorCaptured 钩子捕获 Vue 错误。

此外，Nuxt 提供了一个 vue:error 钩子，如果任何错误传播到顶层，将会被调用。

如果您使用错误报告框架，可以通过 vueApp.config.errorHandler 提供全局处理程序。即使错误被处理，它也会接收所有 Vue 错误。

export default 
defineNuxtPlugin
((
nuxtApp
) => {
  
nuxtApp
.
vueApp
.
config
.
errorHandler
 = (
error
, 
instance
, 
info
) => {
    // 处理错误，例如报告到服务
  }

  // 也可以
  
nuxtApp
.
hook
('vue:error', (
error
, 
instance
, 
info
) => {
    // 处理错误，例如报告到服务
  })
})

启动错误

如果在启动您的 Nuxt 应用程序时出现任何错误，Nuxt 将调用 app:error 钩子。

这包括：

• 运行 Nuxt 插件
• 处理 app:created 和 app:beforeMount 钩子
• 将您的 Vue 应用渲染为 HTML（在 SSR 期间）
• 挂载应用（在客户端），虽然您应该使用 onErrorCaptured 或 vue:error 钩子处理这种情况
• 处理 app:mounted 钩子

Nitro 服务器错误

您目前无法为这些错误定义服务器端处理程序，但可以渲染错误页面，见 渲染错误页面 部分。

JS 块错误

您可能会遇到块加载错误，这可能是由于网络连接故障或新部署（导致旧的散列 JS 块 URL 无效）。Nuxt 提供内置支持来处理块加载错误，当在路由导航期间块加载失败时，它将执行硬重载。

您可以通过将 experimental.emitRouteChunkError 设置为 false（完全禁用这些错误的钩子）或设置为 manual（如果您想自行处理它们）来更改此行为。如果您想手动处理块加载错误，可以查看 自动实现 获取灵感。

错误页面

在服务器生命周期中可能会发生错误，例如：

• 处理您的 Nuxt 插件
• 将您的 Vue 应用渲染为 HTML
• 服务器 API 路由抛出错误

在客户端，错误可能发生在：

• 处理您的 Nuxt 插件
• 挂载应用前 (app:beforeMount 钩子)
• 如果错误未通过 onErrorCaptured 或 vue:error 钩子处理，则挂载应用
• 在浏览器中初始化并挂载 Vue 应用 (app:mounted)。

通过在您的应用程序源目录中添加 ~/error.vue 来自定义默认错误页面，和 app.vue 并存。

<script setup lang="ts">
import type { NuxtError } from '#app'

const props = defineProps({
  error: Object as () => NuxtError
})

const handleError = () => clearError({ redirect: '/' })
</script>

<template>
  <div>
    <h2>{{ error.statusCode }}</h2>
    <button @click="handleError">清除错误</button>
  </div>
</template>

对于自定义错误，我们强烈建议使用可以在页面/组件设置函数中调用的 onErrorCaptured 组合，或者在 Nuxt 插件中配置的 vue:error 运行时钩子。

export default 
defineNuxtPlugin
(
nuxtApp
 => {
  
nuxtApp
.
hook
('vue:error', (
err
) => {
    //
  })
})

当您准备好移除错误页面时，可以调用 clearError 助手函数，该函数接受可选的重定向路径（例如，如果您想导航到一个“安全”页面）。

错误工具

useError

function useError (): Ref<Error | { url, statusCode, statusMessage, message, description, data }>

该函数将返回正在处理的全局 Nuxt 错误。

createError

function createError (err: string | { cause, data, message, name, stack, statusCode, statusMessage, fatal }): Error

创建一个带有附加元数据的错误对象。您可以传递一个字符串作为错误 message，或者一个包含错误属性的对象。它可以在应用的 Vue 和服务器部分中使用，并且旨在被抛出。

如果您抛出一个使用 createError 创建的错误：

• 在服务器端，它将触发全屏错误页面，您可以使用 clearError 清除。
• 在客户端，它将为您处理一个非致命错误。如果您需要触发全屏错误页面，则可以通过设置 fatal: true 来实现。

<script setup lang="ts">
const 
route
 = 
useRoute
()
const { 
data
 } = await 
useFetch
(`/api/movies/${
route
.
params
.
slug
}`)

if (!
data
.
value
) {
  throw 
createError
({
    
statusCode
: 404,
    
statusMessage
: '页面未找到'
  })
}
</script>

showError

function showError (err: string | Error | { statusCode, statusMessage }): Error

您可以在客户端的任何时刻调用此函数，或（在服务器端）直接在中间件、插件或 setup() 函数中调用。它将触发全屏错误页面，您可以使用 clearError 清除。

建议使用 throw createError() 代替。

clearError

function clearError (options?: { redirect?: string }): Promise<void>

该函数将清除当前处理的 Nuxt 错误。它还接受一个可选的重定向路径（例如，如果您想导航到一个“安全”页面）。

组件中的错误渲染

Nuxt 还提供了一个 <NuxtErrorBoundary> 组件，允许您在应用内处理客户端错误，而无需用错误页面替换整个网站。

该组件用于处理其默认插槽中发生的错误。在客户端，它将防止错误向上传播并渲染 #error 插槽。

#error 插槽将接收 error 作为属性。（如果您设置 error = null，则会触发重新渲染默认插槽；您需要确保错误完全解决，否则错误插槽将再次渲染。）

<template>
  <!-- 一些内容 -->
  <NuxtErrorBoundary @error="someErrorLogger">
    <!-- 您可以使用默认插槽渲染您的内容 -->
    <template #error="{ error, clearError }">
      您可以在这里本地显示错误：{{ error }}
      <button @click="clearError">
        这将清除错误。
      </button>
    </template>
  </NuxtErrorBoundary>
</template>