[nextjs 번역] 에러 핸들링(Error Handling)

원문: Getting Started: Error Handling | Next.js

Next.js에서 에러는 크게 예상 가능한 에러(expected errors)와 예상치 못한 예외(uncaught exceptions)로 나눌 수 있습니다. 이 문서에서는 두 가지 에러를 처리하는 방법을 안내합니다.

예상 가능한 에러 처리하기

예상 가능한 에러란, 서버 폼 검증 실패, 요청 실패 등 애플리케이션의 정상 동작 중에 발생할 수 있는 에러입니다. 이런 에러는 명시적으로 처리하여 클라이언트에 반환해야 합니다.

서버 함수(Server Functions)에서의 처리

서버 함수에서 예상 가능한 에러는 try/catch로 throw하지 않고, 반환값으로 모델링하는 것이 좋습니다. 예를 들어, useActionState 훅과 함께 사용하면 에러 메시지를 UI에 표시할 수 있습니다.

// app/actions.ts
'use server'
export async function createPost(prevState: any, formData: FormData) {
  const title = formData.get('title')
  const content = formData.get('content')
  const res = await fetch('https://api.vercel.app/posts', {
    method: 'POST',
    body: { title, content },
  })
  const json = await res.json()
  if (!res.ok) {
    return { message: 'Failed to create post' }
  }
}

// app/ui/form.tsx
'use client'
import { useActionState } from 'react'
import { createPost } from '@/app/actions'

const initialState = { message: '' }

export function Form() {
  const [state, formAction, pending] = useActionState(createPost, initialState)
  return (
    <form action={formAction}>
      <label htmlFor="title">Title</label>
      <input type="text" id="title" name="title" required />
      <label htmlFor="content">Content</label>
      <textarea id="content" name="content" required />
      {state?.message && <p aria-live="polite">{state.message}</p>}
      <button disabled={pending}>Create Post</button>
    </form>
  )
}

서버 컴포넌트(Server Components)에서의 처리

서버 컴포넌트에서 데이터를 패칭할 때, 응답에 따라 조건부로 에러 메시지를 렌더링하거나 리다이렉트할 수 있습니다.

// app/page.tsx
export default async function Page() {
  const res = await fetch(`https://...`)
  const data = await res.json()
  if (!res.ok) {
    return 'There was an error.'
  }
  return '...'
}

notFound 함수와 not-found.js 파일

라우트 세그먼트 내에서 notFound() 함수를 호출하고, not-found.js 파일을 만들어 404 UI를 표시할 수 있습니다.

// app/blog/[slug]/page.tsx
import { getPostBySlug } from '@/lib/posts'

export default async function Page({ params }: { params: { slug: string } }) {
  const { slug } = await params
  const post = getPostBySlug(slug)
  if (!post) {
    notFound()
  }
  return <div>{post.title}</div>
}

// app/blog/[slug]/not-found.tsx
export default function NotFound() {
  return <div>404 - Page Not Found</div>
}

예상치 못한 예외 처리하기 (Uncaught Exceptions)

예상치 못한 예외는 버그나 비정상적인 상황에서 발생하는 에러로, 에러 바운더리(error boundary)에서 처리해야 합니다.

중첩 에러 바운더리(Nested error boundaries)

Next.js는 에러 바운더리를 사용해 자식 컴포넌트에서 발생한 에러를 감지하고, 대체 UI를 표시합니다. 라우트 세그먼트에 error.js 파일을 추가해 에러 바운더리를 만들 수 있습니다.

// app/dashboard/error.tsx
'use client' // 에러 바운더리는 반드시 클라이언트 컴포넌트여야 합니다.
import { useEffect } from 'react'

export default function Error({ error, reset }: { error: Error & { digest?: string }, reset: () => void }) {
  useEffect(() => {
    // 에러 로깅 서비스로 에러 전송
    console.error(error)
  }, [error])
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

에러는 가장 가까운 상위 에러 바운더리로 전파됩니다. 라우트 계층별로 error.tsx를 배치해 세분화된 에러 처리가 가능합니다.

글로벌 에러(Global errors)

루트 레이아웃에서 글로벌 에러를 처리하려면, 루트 app 디렉토리에 global-error.js 파일을 추가하세요. 글로벌 에러 UI는 <html>, <body> 태그를 반드시 포함해야 합니다.

// app/global-error.tsx
'use client'
export default function GlobalError({ error, reset }: { error: Error & { digest?: string }, reset: () => void }) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}