Umgang mit Fehlern

Fehler können in zwei Kategorien unterteilt werden: erwartete Fehler und unbehandelte Ausnahmen. Diese Seite führt Sie durch die Möglichkeiten, wie Sie diese Fehler in Ihrer Next.js-Anwendung behandeln können.

Behandlung erwarteter Fehler

Erwartete Fehler sind solche, die während des normalen Betriebs der Anwendung auftreten können, wie z.B. Fehler aus der serverseitigen Formularvalidierung oder fehlgeschlagene Anfragen. Diese Fehler sollten explizit behandelt und an den Client zurückgegeben werden.

Server-Funktionen

Sie können den useActionState-Hook verwenden, um erwartete Fehler in Server-Funktionen zu behandeln.

Für diese Fehler sollten Sie try/catch-Blöcke vermeiden und keine Fehler werfen. Modellieren Sie erwartete Fehler stattdessen als Rückgabewerte.

'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' }
  }
}

Sie können Ihre Aktion an den useActionState-Hook übergeben und den zurückgegebenen state verwenden, um eine Fehlermeldung anzuzeigen.

'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-Komponenten

Beim Abrufen von Daten innerhalb einer Server-Komponente können Sie die Antwort verwenden, um eine Fehlermeldung bedingt anzuzeigen oder eine redirect durchzuführen.

export default async function Page() {
  const res = await fetch(`https://...`)
  const data = await res.json()

  if (!res.ok) {
    return 'There was an error.'
  }

  return '...'
}

Nicht gefunden

Sie können die notFound-Funktion innerhalb eines Routensegments aufrufen und die not-found.js-Datei verwenden, um eine 404-Benutzeroberfläche anzuzeigen.

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>
}

Behandlung unbehandelter Ausnahmen

Unbehandelte Ausnahmen sind unerwartete Fehler, die auf Bugs oder Probleme hinweisen, die während des normalen Ablaufs Ihrer Anwendung nicht auftreten sollten. Diese sollten durch das Werfen von Fehlern behandelt werden, die dann von Fehlergrenzen abgefangen werden.

Verschachtelte Fehlergrenzen

Next.js verwendet Fehlergrenzen, um unbehandelte Ausnahmen zu verwalten. Fehlergrenzen fangen Fehler in ihren untergeordneten Komponenten ab und zeigen eine Fallback-Benutzeroberfläche anstelle der abgestürzten Komponentenstruktur an.

Erstellen Sie eine Fehlergrenze, indem Sie eine error.js-Datei innerhalb eines Routensegments hinzufügen und eine React-Komponente exportieren:

'use client' // Fehlergrenzen müssen Client-Komponenten sein

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Protokollieren Sie den Fehler in einem Fehlerberichtsdienst
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Etwas ist schiefgelaufen!</h2>
      <button
        onClick={
          // Versuchen Sie, sich durch erneutes Rendern des Segments zu erholen
          () => reset()
        }
      >
        Erneut versuchen
      </button>
    </div>
  )
}

Fehler steigen zur nächstgelegenen übergeordneten Fehlergrenze auf. Dies ermöglicht eine granulare Fehlerbehandlung durch Platzieren von error.tsx-Dateien auf verschiedenen Ebenen in der Routen-Hierarchie.

Verschachtelte Fehlerkomponenten-Hierarchie

Globale Fehler

Weniger häufig, aber möglich, können Sie Fehler im Root-Layout mit der global-error.js-Datei behandeln, die sich im Root-App-Verzeichnis befindet, selbst bei Nutzung von Internationalisierung. Die globale Fehler-Benutzeroberfläche muss ihre eigenen <html>- und <body>-Tags definieren, da sie das Root-Layout oder Template ersetzt, wenn sie aktiv ist.

'use client' // Fehlergrenzen müssen Client-Komponenten sein

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    // global-error muss html- und body-Tags enthalten
    <html>
      <body>
        <h2>Etwas ist schiefgelaufen!</h2>
        <button onClick={() => reset()}>Erneut versuchen</button>
      </body>
    </html>
  )
}

Behandlung erwarteter Fehler

Server-Funktionen

Server-Komponenten

Nicht gefunden

Behandlung unbehandelter Ausnahmen

Verschachtelte Fehlergrenzen

Globale Fehler

Weiterleitung (redirect)

error.js

notFound

not-found.js

On this page