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 런타임 Nuxt 훅을 사용하는 것을 강력히 권장합니다.

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 및 서버 부분 모두에서 사용할 수 있으며, throw할 수 있도록 설계되었습니다.

createError로 생성된 오류를 throw하면:

• 서버 측에서는 전체 화면 오류 페이지를 트리거하며, 이는 clearError로 지울 수 있습니다.
• 클라이언트 측에서는 처리할 수 있는 비치명적 오류를 throw합니다. 전체 화면 오류 페이지를 트리거하려면 fatal: true로 설정할 수 있습니다.

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

if (!data.value) {
  throw createError({
    statusCode: 404,
    statusMessage: '페이지를 찾을 수 없습니다'
  })
}

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를 prop으로 받습니다. (만약 error = null로 설정하면 기본 슬롯을 다시 렌더링하게 됩니다; 오류가 완전히 해결되었는지 먼저 확인해야 하며, 그렇지 않으면 오류 슬롯이 두 번째로 렌더링됩니다.)

<template>
  <!-- 일부 콘텐츠 -->
  <NuxtErrorBoundary @error="someErrorLogger">
    <!-- 기본 슬롯을 사용하여 콘텐츠를 렌더링합니다 -->
    <template #error="{ error, clearError }">
      여기에서 로컬로 오류를 표시할 수 있습니다: {{ error }}
      <button @click="clearError">
        이 버튼은 오류를 지웁니다.
      </button>
    </template>
  </NuxtErrorBoundary>
</template>