Nuxt é um framework full-stack, o que significa que existem várias fontes de erros de tempo de execução do usuário que não podem ser evitados e que podem ocorrer em diferentes contextos:

• Erros durante o ciclo de vida de renderização do Vue (SSR & CSR)
• Erros de inicialização do servidor e do cliente (SSR + CSR)
• Erros durante o ciclo de vida do servidor Nitro (diretório server/)
• Erros ao baixar chunks de JS

Erros do Vue

Você pode conectar-se aos erros do Vue usando onErrorCaptured.

Além disso, o Nuxt fornece um hook vue:error que será chamado se algum erro se propagar até o nível superior.

Se você estiver usando um framework de relatório de erros, pode fornecer um manipulador global através de vueApp.config.errorHandler. Ele receberá todos os erros do Vue, mesmo que sejam tratados.

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.config.errorHandler = (error, instance, info) => {
    // tratar erro, por exemplo, relatar a um serviço
  }

  // Também é possível
  nuxtApp.hook('vue:error', (error, instance, info) => {
    // tratar erro, por exemplo, relatar a um serviço
  })
})

Erros de Inicialização

O Nuxt chamará o hook app:error se houver algum erro ao iniciar sua aplicação Nuxt.

Isso inclui:

• execução de plugins do Nuxt
• processamento dos hooks app:created e app:beforeMount
• renderização de sua aplicação Vue para HTML (durante SSR)
• montagem da aplicação (no lado do cliente), embora você deva tratar este caso com onErrorCaptured ou com vue:error
• processamento do hook app:mounted

Erros do Servidor Nitro

Atualmente, você não pode definir um manipulador do lado do servidor para esses erros, mas pode renderizar uma página de erro, veja a seção Renderizar uma Página de Erro.

Erros com Chunks de JS

Você pode encontrar erros de carregamento de chunks devido a uma falha de conectividade de rede ou a uma nova implantação (que invalida seus URLs antigos de chunks de JS com hash). O Nuxt fornece suporte embutido para tratar erros de carregamento de chunks realizando um recarregamento completo quando um chunk falha ao carregar durante a navegação de rota.

Você pode alterar esse comportamento configurando experimental.emitRouteChunkError para false (para desativar a conexão com esses erros) ou para manual se quiser tratá-los você mesmo. Se quiser tratar erros de carregamento de chunks manualmente, você pode conferir a implementação automática para ideias.

Página de Erro

Um erro pode ocorrer durante o ciclo de vida do servidor quando:

• processando seus plugins do Nuxt
• renderizando sua aplicação Vue em HTML
• uma rota de API do servidor lança um erro

Também pode ocorrer no lado do cliente quando:

• processando seus plugins do Nuxt
• antes de montar a aplicação (hook app:beforeMount)
• montando sua aplicação se o erro não foi tratado com onErrorCaptured ou hook vue:error
• a aplicação Vue é inicializada e montada no navegador (app:mounted).

Personalize a página de erro padrão adicionando ~/error.vue no diretório de origem de sua aplicação, ao lado de 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">Limpar erros</button>
  </div>
</template>

Para erros personalizados, recomendamos fortemente usar o composable onErrorCaptured que pode ser chamado em uma função de configuração de página/componente ou o hook de tempo de execução vue:error do Nuxt que pode ser configurado em um plugin do Nuxt.

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

Quando estiver pronto para remover a página de erro, você pode chamar a função auxiliar clearError, que aceita um caminho opcional para redirecionar (por exemplo, se você quiser navegar para uma página 'segura').

Utilitários de Erro

useError

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

Esta função retornará o erro global do Nuxt que está sendo tratado.

createError

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

Crie um objeto de erro com metadados adicionais. Você pode passar uma string para ser definida como a message do erro ou um objeto contendo propriedades do erro. É utilizável tanto nas partes Vue quanto no servidor de sua aplicação, e é destinado a ser lançado.

Se você lançar um erro criado com createError:

• no lado do servidor, ele acionará uma página de erro em tela cheia que você pode limpar com clearError.
• no lado do cliente, ele lançará um erro não fatal para você tratar. Se precisar acionar uma página de erro em tela cheia, você pode fazer isso definindo fatal: true.

const route = useRoute()
const { data } = await useFetch(`/api/movies/${route.params.slug}`)

if (!data.value) {
  throw createError({
    statusCode: 404,
    statusMessage: 'Página Não Encontrada'
  })
}

showError

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

Você pode chamar esta função a qualquer momento no lado do cliente, ou (no lado do servidor) diretamente dentro de middleware, plugins ou funções setup(). Ela acionará uma página de erro em tela cheia que você pode limpar com clearError.

Recomenda-se em vez disso usar throw createError().

clearError

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

Esta função limpará o erro do Nuxt atualmente tratado. Ela também aceita um caminho opcional para redirecionar (por exemplo, se você quiser navegar para uma página 'segura').

Renderizar Erro em Componente

O Nuxt também fornece um componente <NuxtErrorBoundary> que permite tratar erros do lado do cliente dentro de sua aplicação, sem substituir todo o seu site por uma página de erro.

Este componente é responsável por tratar erros que ocorrem dentro de seu slot padrão. No lado do cliente, ele impedirá que o erro se propague para o nível superior e renderizará o slot #error em vez disso.

O slot #error receberá error como uma prop. (Se você definir error = null, ele acionará a re-renderização do slot padrão; você precisará garantir que o erro esteja totalmente resolvido primeiro ou o slot de erro será renderizado novamente.)

<template>
  <!-- algum conteúdo -->
  <NuxtErrorBoundary @error="someErrorLogger">
    <!-- Você usa o slot padrão para renderizar seu conteúdo -->
    <template #error="{ error, clearError }">
      Você pode exibir o erro localmente aqui: {{ error }}
      <button @click="clearError">
        Isso limpará o erro.
      </button>
    </template>
  </NuxtErrorBoundary>
</template>