12. 오류 처리(Error Handling)

Nuxt 3는 풀 스택 프레임워크이다. 즉, 다양한 상황에서 발생할 수 있는 예방할 수 없는 사용자 런타임 오류의 원인이 여러 가지 있다는 의미다.

• Vue 렌더링 수명 주기 중 오류(SSR 및 CSR)
• Nitro 서버 수명 주기 중 오류(server/ 디렉토리)
• 서버 및 클라이언트 시작 오류(SSR + CSR)
• JS 청크 다운로드 중 오류 발생

 

Vue 렌더링 수명주기

onErrorCaptured 를 사용하여 Vue 오류를 연결할 수 있다 .

또한 Nuxt는 오류가 최상위 수준까지 전파되는 경우 호출되는 후크 vue:error 를 제공한다.

오류 보고 프레임워크를 사용하는 경우, vueApp.config.errorHandler 를 통해 전역 처리기를 제공할 수 있다 . 처리되더라도 모든 Vue 오류를 수신한다.

// plugins/error-handler.ts

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.config.errorHandler = (error, instance, info) => {
    // handle error, e.g. report to a service
  }

  // Also possible
  nuxtApp.hook('vue:error', (error, instance, info) => {
    // handle error, e.g. report to a service
  })
})

vue:error 후크는 수명 주기 후크 onErrorCaptured를 기반으로 한다.

 

시작 오류

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 로 설정하여 이 동작을 변경할 수 있다. 혹은, 청크 로딩 오류를 수동으로 처리하려면 아이디어 자동 구현을 확인하자.

 

오류 페이지

Nuxt가 치명적인 오류(서버에서 처리되지 않은 오류 또는 클라이언트에서 fatal: true 를 통해 생성된 오류)를 발견하면 JSON 응답( Accept: application/json 헤더로 요청한 경우)을 렌더링하거나 전체 화면 오류 페이지를 트리거한다.

다음과 같은 경우 서버 수명 주기 동안 오류가 발생할 수 있습니다.

• Nuxt 플러그인 처리 중.
• Vue 앱을 HTML로 렌더링하기.
• 서버 API 경로에서 오류가 발생.

다음과 같은 경우 클라이언트 측에서도 발생할 수 있다.

• Nuxt 플러그인 처리 중.
• 애플리케이션을 마운트하기 전( app:beforeMount 후크).
• 오류가 onErrorCaptured 또는 vue:error 후크로 처리되지 않은 경우의 앱 마운트.
• Vue 앱이 초기화되고 브라우저( app:mounted)에 마운트 될때.

참고) Nuxt 라이프사이클 후크

app.vue 와 함께 source 디렉토리에 ~/error.vue 파일을 추가하여 기본 오류페이지를 사용자 지정한다.

<!--
error.vue
-->

<script setup lang="ts">
const props = defineProps({
  error: Object
})

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

<template>
  <div>
    <h2>{{ error.statusCode }}</h2>
    <button @click="handleError">Clear errors</button>
  </div>
</template>

'오류 페이지'라고 불리기는 하지만 경로가 아니므로 ~/pages 디렉터리에 배치하면 안된다. 같은 이유로 이 페이지 내에서는 definePageMeta 을 사용하면 안된다.

 

오류 페이지에는 error처리할 오류가 포함된 단일 prop 이 있다.
error 객체는 다음 필드를 제공한다.

{
  url: string
  statusCode: number
  statusMessage: string
  message: string
  description: string
  data: any
}

오류에 사용자 정의 필드가 있으면 손실되므로, 대신 data 에 할당해야 합니다:

throw createError({
  statusCode: 404,
  statusMessage: 'Page Not Found',
  data: {
    myCustomField: true
  }
})

맞춤 오류의 경우 페이지/컴포넌트 setup 함수에서 호출할 수 있는 onErrorCaptured  컴포저블 또는 nuxt 플러그인에서 구성할 수 있는 런타임 nuxt 후크  vue:error 를 사용하는 것이 좋다.

// plugins/error-handler.ts

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

오류 페이지를 제거할 준비가 되면 리디렉션할 선택적 경로를 사용하는 헬퍼 함수 clearError 를 호출할 수 있다(예: '안전한' 페이지로 이동하려는 경우).

 

$route 또는 useRouter 등의 Nuxt 플러그인에 종속된 항목을 사용하기 전에 플러그인에서 오류가 발생한 경우 오류를 삭제할 때까지 다시 실행되지 않는지 확인해야한다.

Node 16에서 실행 중이고 오류 페이지를 렌더링할 때 쿠키를 설정한 경우 이전에 설정한 쿠키를 덮어쓴다 . Node 16이 2023년 9월에 수명이 종료되므로 최신 버전의 Node를 사용하는 것이 좋다.

 

오류 유틸리티

useError

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

이 함수는 처리 중인 전역 Nuxt 오류를 반환합니다. useError 참고

 

createError

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

추가 메타데이터를 사용하여 오류 개체를 만든다. 그러면, 앱의 Vue 및 Server 부분 모두에서 사용할 수 있으며 오류 개체가 던져지게 된다.

createError 로 생성된 오류가 발생하는 경우에는 :

• 서버 측에서는 clearError 로 지울 수 있는 전체 화면 오류 페이지가 트리거된다 .
• 클라이언트 측에서는 사용자가 처리할 수 있는 치명적이지 않은 오류가 발생한다. 전체 화면 오류 페이지를 실행해야 하는 경우 fatal: true 를 설정하여 수행할 수 있다.

<!--
pages/movies/[slug].vue
-->

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

if (!data.value) {
  throw createError({
    statusCode: 404,
    statusMessage: 'Page Not Found'
  })
}
</script>

참고) createError

 

showError

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

클라이언트 측에서 언제든지 또는 (서버 측에서) 미들웨어, 플러그인 또는 setup()함수 내에서 직접 이 함수를 호출할 수 있다. clearError 로 지울 수 있는 전체 화면 오류 페이지가 실행된다.

 

이보다 throw createError() 사용하는 것이 권장된다.

 

참고) showError

 

clearError

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

이 함수는 현재 처리된 Nuxt 오류를 지운다. 또한 리디렉션할 선택적 경로도 필요하다(예: '안전한' 페이지로 이동하려는 경우).

참고) clearError util

컴포넌트의 렌더링 오류

Nuxt는 또한 전체 사이트를 오류 페이지로 바꾸지 않고도 앱 내에서 클라이언트 측 오류를 처리할 수 있는 <NuxtErroBoundary> 컴포넌트를 제공한다.

이 컴포넌트는 기본 슬롯 내에서 발생하는 오류를 처리한다. 클라이언트 측에서는 오류가 최상위 수준으로 퍼지는 것을 방지하고 대신 #error 슬롯을 렌더링한다.

#error 슬롯은 prop 로 error 를 받게된다. ( error = null  이 설정되면 기본 슬롯이 다시 렌더링된다. 먼저 오류가 완전히 해결되었는지 확인해야한다. 그렇지 않으면 오류 슬롯이 두 번째로 렌더링된다.)

다른 경로로 이동하면 오류가 자동으로 지워진다.

<template>
  <!-- some content -->
  <NuxtErrorBoundary @error="someErrorLogger">
    <!-- You use the default slot to render your content -->
    <template #error="{ error, clearError }">
      You can display the error locally here: {{ error }}
      <button @click="clearError">
        This will clear the error.
      </button>
    </template>
  </NuxtErrorBoundary>
</template>

예제) Docs > Examples > Advanced > Error Handling