Fehlerbehandlung

Fehler können in zwei Kategorien unterteilt werden: erwartete Fehler und unerwartete Ausnahmen:

• Erwartete Fehler als Rückgabewerte modellieren: Vermeiden Sie die Verwendung von try/catch für erwartete Fehler in Server-Aktionen. Verwenden Sie useFormState, um diese Fehler zu verwalten und an den Client zurückzugeben.
• Verwenden Sie Fehler-Boundaries für unerwartete Fehler: Implementieren Sie Fehler-Boundaries mit error.tsx- und global-error.tsx-Dateien, um unerwartete Fehler zu behandeln und eine Fallback-Benutzeroberfläche bereitzustellen.

Behandlung erwarteter Fehler

Erwartete Fehler sind solche, die während des normalen Betriebs der Anwendung auftreten können, wie etwa bei serverseitiger Formularvalidierung oder fehlgeschlagenen Anfragen. Diese Fehler sollten explizit behandelt und an den Client zurückgegeben werden.

Behandlung erwarteter Fehler aus Server-Aktionen

Verwenden Sie den useFormState-Hook, um den Zustand von Server-Aktionen zu verwalten, einschließlich der Fehlerbehandlung. Dieser Ansatz vermeidet try/catch-Blöcke für erwartete Fehler, die als Rückgabewerte und nicht als geworfene Ausnahmen modelliert werden sollten.

'use server'
 
import { redirect } from 'next/navigation'
 
export async function createUser(prevState: any, formData: FormData) {
  const res = await fetch('https://...')
  const json = await res.json()
 
  if (!res.ok) {
    return { message: 'Bitte geben Sie eine gültige E-Mail-Adresse ein' }
  }
 
  redirect('/dashboard')
}

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

'use client'
 
import { useFormState } from 'react'
import { createUser } from '@/app/actions'
 
const initialState = {
  message: '',
}
 
export function Signup() {
  const [state, formAction] = useFormState(createUser, initialState)
 
  return (
    <form action={formAction}>
      <label htmlFor="email">E-Mail</label>
      <input type="text" id="email" name="email" required />
      {/* ... */}
      <p aria-live="polite">{state?.message}</p>
      <button>Registrieren</button>
    </form>
  )
}

Hinweis: Diese Beispiele verwenden Reacts useFormState-Hook, der im Next.js App Router enthalten ist. Wenn Sie React 19 verwenden, verwenden Sie stattdessen useActionState. Weitere Informationen finden Sie in der React-Dokumentation.

Sie könnten den zurückgegebenen Status auch verwenden, um eine Toast-Nachricht aus der Client-Komponente anzuzeigen.

Behandlung erwarteter Fehler aus Server-Komponenten

Bei der Datenabfrage innerhalb einer Server-Komponente können Sie die Antwort verwenden, um eine Fehlermeldung bedingt zu rendern oder redirect zu verwenden.

export default async function Page() {
  const res = await fetch(`https://...`)
  const data = await res.json()
 
  if (!res.ok) {
    return 'Es ist ein Fehler aufgetreten.'
  }
 
  return '...'
}

Unerwartete Ausnahmen

Unerwartete Ausnahmen sind Fehler, die auf Fehler oder Probleme hinweisen, die während des normalen Ablaufs Ihrer Anwendung nicht auftreten sollten. Diese sollten durch Werfen von Fehlern behandelt werden, die dann von Fehler-Boundaries abgefangen werden.

• Häufig: Behandeln Sie unerwartete Fehler unterhalb des Haupt-Layouts mit error.js.
• Optional: Behandeln Sie granulare unerwartete Fehler mit verschachtelten error.js-Dateien (z.B. app/dashboard/error.js)
• Selten: Behandeln Sie unerwartete Fehler im Haupt-Layout mit global-error.js.

Verwendung von Fehler-Boundaries

Next.js verwendet Fehler-Boundaries, um unerwartete Ausnahmen zu behandeln. Fehler-Boundaries fangen Fehler in ihren untergeordneten Komponenten ab und zeigen eine Fallback-Benutzeroberfläche anstelle des abgestürzten Komponentenbaums an.

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

'use client' // Fehler-Boundaries müssen Client-Komponenten sein
 
import { useEffect } from 'react'
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Fehler an einen Fehlerberichterstattungsdienst protokollieren
    console.error(error)
  }, [error])
 
  return (
    <div>
      <h2>Etwas ist schiefgelaufen!</h2>
      <button
        onClick={
          // Versuch, durch erneutes Rendern des Segments wiederherzustellen
          () => reset()
        }
      >
        Erneut versuchen
      </button>
    </div>
  )
}

Wenn Sie möchten, dass Fehler zur übergeordneten Fehler-Boundary weitergeleitet werden, können Sie beim Rendern der error-Komponente einen Fehler werfen.

Behandlung von Fehlern in verschachtelten Routen

Fehler werden zur nächsten übergeordneten Fehler-Boundary weitergeleitet. Dies ermöglicht eine granulare Fehlerbehandlung durch Platzierung von error.tsx-Dateien auf verschiedenen Ebenen in der Routen-Hierarchie.

Behandlung globaler Fehler

Seltener können Sie Fehler im Haupt-Layout mit app/global-error.js behandeln, das sich im Stammverzeichnis der App befindet, auch bei Verwendung von Internationalisierung. Die globale Fehler-Benutzeroberfläche muss eigene <html>- und <body>-Tags definieren, da sie das Haupt-Layout oder die Vorlage ersetzt, wenn sie aktiv ist.

'use client' // Fehler-Boundaries 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>
  )
}