0Pricing
React Academy · Lektion

Hydration-Fehler: Ursachen und Lösungen

Erkennen Sie Abweichungen zwischen dem HTML von Server und Client und beheben Sie sie mit suppressHydrationWarning.

Hydration-Fehler: Ursachen und Lösungen ist eine kostenlose React Academy-Lektion auf CoddyKit. Dies ist Lektion 2 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des React Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der React Academy-Kurs umfasst insgesamt 4 Lektionen.

Was ist ein Hydration-Fehler?

Ein Hydration-Fehler tritt auf, wenn das vom Server gerenderte HTML nicht mit dem virtuellen DOM übereinstimmt, das React auf dem Client erwartet. React protokolliert eine Warnung und rendert die Komponente von Grund auf neu, wodurch ein kurzes Aufflackern entsteht.

Häufige Ursache 1: Zufallswerte

Wenn Sie Math.random(), Date.now() oder crypto.randomUUID() während des Renderns verwenden, entstehen auf Server und Client unterschiedliche Werte.

// Bad — different on server vs client:
<div id={Math.random().toString()}>...</div>

// Fix — use useId() (stable across server/client):
import { useId } from 'react';
function Component() {
  const id = useId();
  return <div id={id}>...</div>;
}

Häufige Ursache 2: Nur im Browser verfügbare APIs

Das Auslesen von localStorage, window.innerWidth oder navigator während des Renderns verursacht auf dem Server einen Fehler oder erzeugt unterschiedliche Werte.

// Bad — localStorage doesn't exist on server:
<div>{localStorage.getItem('theme')}</div>

// Fix — read in useEffect (client-only):
const [theme, setTheme] = useState('light');
useEffect(() => {
  setTheme(localStorage.getItem('theme') ?? 'light');
}, []);

Häufige Ursache 3: Datums- und Zeitformatierung

Die lokalisierte Datumsformatierung gibt auf dem Server (UTC/Node-Gebietsschema) und dem Client (Browser-Gebietsschema) unterschiedliche Zeichenfolgen zurück.

// Risky — locale may differ:
<time>{new Date().toLocaleDateString()}</time>

// Fix — use a consistent locale:
<time>{new Date().toLocaleDateString('en-US', { timeZone: 'UTC' })}</time>

Häufige Ursache 4: Ungültige HTML-Verschachtelung

React erzeugt das Client-HTML aus dem virtuellen DOM. Eine ungültige HTML-Verschachtelung (z. B. <p> innerhalb von <p>) veranlasst Browser jedoch, das DOM unterschiedlich umzu strukturieren, wodurch Abweichungen entstehen.

// Bad — browser auto-closes the nested <p>:
<p>Outer <p>Inner</p> text</p>

// Fix — use <div> or correct semantic elements:
<div>Outer <p>Inner</p> text</div>

Häufige Ursache 5: Bedingtes Rendern anhand des Status

Komponenten, die abhängig von einem nur auf dem Client verfügbaren Status (z. B. Benutzer-Authentifizierung oder Bildschirmbreite) unterschiedlich gerendert werden, weisen Abweichungen auf, weil der Server ohne diesen Status rendert.

// Bad — server renders 'Guest', client re-renders 'Alice' immediately:
<h1>{user?.name ?? 'Guest'}</h1>

// Fix — use a mounted guard to defer client-only rendering:
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return <h1>Guest</h1>; // match server output

suppressHydrationWarning

Verwenden Sie suppressHydrationWarning für Elemente, bei denen Abweichungen beabsichtigt sind (z. B. clientseitig formatierte Zeitstempel). Dadurch wird die Warnung nur für dieses Element unterdrückt.

<time suppressHydrationWarning dateTime={isoDate}>
  {new Date(isoDate).toLocaleString()}
</time>

Dynamischer Import mit ssr: false

Verwenden Sie in Next.js dynamic(fn, { ssr: false }), um zu verhindern, dass eine Komponente überhaupt auf dem Server gerendert wird. Dadurch lassen sich Hydration-Abweichungen bei rein clientseitigen Komponenten vermeiden.

import dynamic from 'next/dynamic';

const ClientOnlyChart = dynamic(() => import('./Chart'), { ssr: false });

export default function Dashboard() {
  return <ClientOnlyChart />; // only renders in the browser
}

Hydration-Fehler debuggen

React 18 protokolliert im Entwicklungsmodus detaillierte Hydration-Fehlermeldungen, die die genaue Abweichung im DOM-Knoten anzeigen. Verwenden Sie die DevTools des Browsers, um das Server-HTML mit dem React-Baum zu vergleichen.

Stabile IDs mit useId

useId() erzeugt stabile, eindeutige IDs, die bei Render-Vorgängen auf Server und Client übereinstimmen. Verwenden Sie den Hook für id/htmlFor-Paare und ARIA-Attribute.

function FormInput({ label }: { label: string }) {
  const id = useId();
  return (
    <div>
      <label htmlFor={id}>{label}</label>
      <input id={id} />
    </div>
  );
}

Auf Hydration-Fehler testen

Führen Sie Ihre Next.js-App im Entwicklungsmodus aus (npm run dev) und beobachten Sie die Browserkonsole. Hydration-Abweichungen erscheinen als rote Warnungen mit Komponenten-Stacktraces.

Schnelltest

Was ist die beste Lösung für eine Komponente, die sich auf Server und Client unterschiedlich rendert, weil sie aus localStorage liest?

Zusammenfassung

Hydration-Abweichungen entstehen durch Zufallswerte, nur im Browser verfügbare APIs, gebietsschemaabhängige Formatierung, ungültige HTML-Verschachtelung und clientseitig bedingtes Rendern. Beheben Sie sie mit useId(), useEffect für clientseitigen Status, suppressHydrationWarning für beabsichtigte Unterschiede und dynamic({ ssr: false }) für rein clientseitige Komponenten.

Häufig gestellte Fragen

Ist die Lektion „Hydration-Fehler: Ursachen und Lösungen“ kostenlos?

Ja — der vollständige Text von „Hydration-Fehler: Ursachen und Lösungen“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des React Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der React Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Hydration-Fehler: Ursachen und Lösungen“?

Erkennen Sie Abweichungen zwischen dem HTML von Server und Client und beheben Sie sie mit suppressHydrationWarning. Du übst React Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um React Academy zu starten?

Keine Vorkenntnisse erforderlich. React Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 2 von 4.

Wie lange dauert die Lektion „Hydration-Fehler: Ursachen und Lösungen“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser React Academy-Lektion Code schreiben und ausführen?

Ja. Jede React Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

  1. So funktioniert React SSR unter der Haube
  2. Hydration-Fehler: Ursachen und Lösungen
  3. Selektive Hydration und Streaming-HTML
  4. Islands-Architecture-Pattern
← Zurück zu React Academy