[Nuxt3] 에러 핸들링

Nuxt에서 제공하는 주요 에러 처리 방법

Nuxt에서는 다음과 같은 함수를 통해 에러 처리를 지원합니다:

• createError: 사용자 정의 에러 객체 생성
• showError: 사용자에게 에러를 표시하고 오류 페이지로 리다이렉트
• useError: 현재 발생한 에러 정보 접근
• clearError: 발생한 에러 상태 초기화 및 페이지 이동 처리
• Lifecycle Hooks: Vue 생명 주기에서 발생하는 에러를 커스텀 처리
• NuxtErrorBoundary: 컴포넌트 레벨의 에러 경계 설정

 

createError로 사용자 정의 에러 생성하기

createError는 서버와 클라이언트 양쪽 환경에서 사용자 정의 에러 객체를 생성할 때 사용합니다. HTTP 상태 코드 및 메시지 등 상세 정보를 포함할 수 있습니다. 주로 서버 측 API에서 에러를 처리하거나 전체 화면 에러 페이지를 표시할 때 활용됩니다.

기본 사용 예시

import { createError } from '#imports';

export default defineEventHandler((event) => {
  const userId = event.context.params.id;

  if (!userId) {
    throw createError({
      statusCode: 400,
      statusMessage: 'Bad Request',
      message: '유효한 사용자 ID가 제공되지 않았습니다.'
    });
  }
});

타입 정의 (TypeScript)

interface NuxtError {
  statusCode?: number;
  statusMessage?: string;
  message?: string;
  fatal?: boolean;
}

치명적인 에러 처리하기 (fatal: true)

에러가 애플리케이션 전체에 영향을 줄 정도로 심각한 경우, fatal: true를 설정하여 애플리케이션 전체를 에러 상태로 전환할 수 있습니다.

throw createError({
  statusCode: 500,
  statusMessage: 'Critical Error',
  message: '치명적인 에러가 발생했습니다.',
  fatal: true
});

 

 

showError로 사용자에게 에러 표시하기

컴포넌트 내에서 발생한 에러를 즉시 사용자에게 표시하고, 전역 에러 페이지(/error.vue)로 이동시키려면 showError를 사용합니다. 이 함수는 클라이언트 측에서 특정 작업 중 에러가 발생했을 때 유용합니다. 또한, showError는 내부적으로 app:error 훅을 호출합니다.

<script setup lang="ts">
import { showError } from '#app';

const fetchData = async () => {
  try {
    await fetch('/api/data');
  } catch (error) {
    showError({
      statusCode: 500,
      statusMessage: 'Internal Server Error',
      message: '데이터를 불러오는 중 에러가 발생했습니다.'
    });
  }
};

fetchData();
</script>

 

 

전역 에러 페이지 (error.vue) 정의하기

Nuxt에서 전역 에러 페이지는 프로젝트 루트에 위치한 error.vue로 정의할 수 있습니다.

<!-- error.vue -->
<template>
  <div class="error-container">
    <h1>{{ error.statusCode }}</h1>
    <p>{{ error.message }}</p>
    <button @click="handleClearError">홈으로 돌아가기</button>
  </div>
</template>

<script setup lang="ts">
import { clearError } from '#app';

defineProps<{ error: any }>();

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

 

현재 에러 상태 관리 (useError 및 clearError)

현재 에러 정보 확인 (useError)

발생한 에러 정보를 실시간으로 접근할 수 있습니다.

<script setup lang="ts">
import { useError } from '#app';

const error = useError();

if (error.value) {
  console.log('에러 발생:', error.value.message);
}
</script>

에러 초기화 (clearError)

현재 에러 상태를 초기화하는 방법입니다.

<script setup lang="ts">
import { clearError } from '#app';

const resetError = () => clearError();
</script>

<button @click="resetError">에러 초기화</button>

clearError의 redirect 옵션

clearError 함수를 호출할 때 redirect 옵션을 주면, 에러 초기화 후 특정 페이지로 리다이렉트할 수 있습니다.

clearError({ redirect: '/login' });

 

Lifecycle Hook (app:error & vue:error)에서 커스텀 에러 처리하기

Nuxt는 app:error와 vue:error 같은 Lifecycle Hook을 통해 전역적으로 에러를 감지하고 커스텀 처리할 수 있게 지원합니다.

🚧 Lifecycle Hook은 클라이언트 환경에서만 유효합니다. 따라서 반드시 process.client 조건으로 보호해야 합니다.

// plugins/error-handler.ts
import { Notify } from 'quasar';

export default defineNuxtPlugin((nuxtApp) => {
  if (process.client) {
    nuxtApp.hook('vue:error', (err: unknown) => {
      if (err instanceof Error) {
        Notify.create({ message: err.message, type: 'negative' });
      }
    });

    nuxtApp.hook('app:error', (err: unknown) => {
      console.error('App-level error:', err);
    });
  }
});

 

컴포넌트 레벨 에러 처리 (NuxtErrorBoundary)

컴포넌트 내에서 에러 경계를 설정하려면 NuxtErrorBoundary를 사용할 수 있습니다. <NuxtErrorBoundary> 컴포넌트는 Vue의 onErrorCaptured 훅을 내부적으로 사용합니다. 이 컴포넌트는 클라이언트 측 오류를 처리하는 데에 활용되며, 다음과 같은 이벤트와 슬롯을 제공합니다.

• @error: 이 이벤트는 컴포넌트의 기본 슬롯에서 오류가 발생했을 때 발생합니다. 개발자는 이 이벤트를 활용하여 오류가 발생했을 때 특정 동작을 수행하도록 할 수 있습니다.
• #error: 이 슬롯은 오류가 발생했을 때 표시할 대체 콘텐츠를 지정하는 데에 사용됩니다. 오류가 발생하면 이 슬롯의 내용이 대신 표시됩니다.
• <NuxtPage />에서 에러가 발생하면 #error 슬롯이 렌더링됨.
• handleError 함수에서 에러를 콘솔에 출력.
• reset()을 호출하면 다시 원래 페이지를 렌더링 시도.

<template>
  <NuxtErrorBoundary @error="handleError">
    <template #default>
      <NuxtPage />
    </template>

    <template #error="{ error, reset }">
      <p>에러 발생: {{ error.message }}</p>
      <button @click="reset">다시 시도</button>
    </template>
  </NuxtErrorBoundary>
</template>

<script setup>
const handleError = (error) => {
  console.error("에러 발생:", error);
};
</script>