So deployst du eine React- oder Next.js-App
React- oder Next.js-App deployen
React- oder Next.js-App deployen (inklusive SPA-Rewrites) | We.Inc
Wähle App-Typ und Host und erhalte Build-Befehl, Output-Ordner und die Rewrite-Datei, die 404-Fehler beim Neuladen auf Vercel, Netlify, Cloudflare und GitHub Pages verhindert.
Um eine React-App zu deployen, führst du den Production-Build aus und übergibst den Output-Ordner an einen Host: dist bei Vite, out bei einem statischen Next.js-Export. Single Page Apps brauchen zusätzlich einen Rewrite, der unbekannte Pfade an index.html weiterleitet, sonst liefert das Neuladen eines Deep Links einen 404. Eine vollständige Next.js-App braucht einen Host, der Node.js ausführt.
Build-Output nach App-Typ
- App-Typ
- Build-Befehl
- Hochladen oder ausliefern
- SPA-Rewrite nötig?
- Vite + React
- npm run build
- dist/
- Ja
- Statischer Next.js-Export
- npm run build (output: 'export')
- out/
- Nein, eine HTML-Datei pro Route
- Next.js mit Server-Funktionen
- npm run build, dann npm run start
- .next/ auf einem Node.js-Server
- Nein
Die meisten gescheiterten React-Deployments haben eine von drei Ursachen: den falschen Output-Ordner, einen fehlenden Rewrite für clientseitige Routen oder eine Next.js-Funktion, die einen Server braucht, aber auf einem statischen Host landet. Wähle unten deinen App-Typ und deinen Host, um die genaue Einstellung und Datei für diese Kombination zu sehen, jeweils aus der Dokumentation des Hosts übernommen.
- Wähle die Art deiner App: eine Vite Single Page App, einen statischen Next.js-Export oder eine vollständige Next.js-App.
- Wähle den Host, den du nutzen möchtest.
- Kopiere die Build-Einstellungen und die angezeigte Konfigurationsdatei, committe sie und verbinde das Repository oder lade den Ordner hoch.
- Öffne nach dem ersten Deployment einen Deep Link wie /about direkt und lade ihn neu, um zu prüfen, ob das Routing funktioniert.
- Führe vor deinem ersten Deployment npm run build und die lokale Vorschau aus. Ein Build, der auf deinem Rechner fehlschlägt, schlägt auch beim Host fehl.
- Lege die _redirects-Datei von Netlify in den public/-Ordner von Vite, damit sie bei jedem Build nach dist kopiert wird.
- Variablen mit dem Präfix VITE_ landen im ausgelieferten JavaScript, also speichere dort niemals Geheimnisse.
- Setze bei GitHub-Pages-Projektseiten base in Vite auf '/<repo-name>/', sonst funktioniert kein einziger Asset-Pfad.
Häufige Fragen
Warum zeigt meine React-App beim Neuladen einer Seite einen 404?
Der Router läuft im Browser, aber beim Neuladen fragt der Browser den Server nach einer Datei wie /about/index.html, die es nicht gibt. Ein Rewrite, der für unbekannte Pfade index.html zurückgibt, lässt den Router wieder übernehmen. Jeder Host hat seine eigene Syntax für diese Regel.
Brauche ich auf Cloudflare Pages einen Rewrite?
Nicht, wenn dein Build keine 404.html auf oberster Ebene enthält. Laut der Cloudflare-Dokumentation behandelt Pages das Projekt dann als Single Page App und liefert für jeden Pfad, der keine echte Datei ist, den Root-Index aus.
Kann ich eine Next.js-App auf GitHub Pages deployen?
Nur als statischen Export mit output: 'export'. GitHub Pages liefert Dateien aus und kann den Next.js-Server nicht ausführen, daher stehen dort Funktionen wie Server Actions, Cookies, Rewrites und Rendering auf Abruf nicht zur Verfügung.
Was ist der Unterschied zwischen einem Redirect und einem Rewrite?
Ein Redirect schickt den Browser zu einer neuen URL, wodurch sich die Adresszeile ändert. Ein Rewrite liefert eine andere Datei aus, behält aber die angefragte URL bei, und genau das braucht eine Single Page App. Netlify kennzeichnet einen Rewrite mit dem Status 200.
Wohin gehören Umgebungsvariablen?
Lege sie in den Projekteinstellungen des Hosts fest, nicht in einer committeten .env-Datei. Denk daran, dass Variablen, die an den Browser ausgeliefert werden, öffentlich sind. Schlüssel, die privat bleiben müssen, gehören auf einen Server oder in Serverless Functions.
Schritt eins: ein sauberer Production-Build
- Installiere die Abhängigkeiten mit npm ci aus der Lockfile und führe dann npm run build aus. Bei Vite prüfst du das Ergebnis mit npm run preview, das dist auf Port 4173 ausliefert. Bei Next.js liefert npm run start den Build auf Port 3000 aus.
- Wenn der Build lokal durchläuft, braucht der Host nur drei Einstellungen: den Installationsbefehl, den Build-Befehl und den Output-Ordner. Die meisten Hosts erkennen Vite und Next.js und tragen sie selbst ein.
Schritt zwei: Routing, das ein Neuladen übersteht
- Clientseitige Router ändern die URL, ohne den Server zu fragen. Das funktioniert, bis jemand die Seite neu lädt oder einen geteilten Link öffnet und der Server nach einer Datei sucht, die nicht existiert.
- Die Lösung ist eine Catch-all-Regel, die für Pfade ohne passende Datei index.html mit dem Status 200 zurückgibt. Statische Exporte von Next.js umgehen das Problem, weil jede Route ihre eigene HTML-Datei bekommt.
Schritt drei: eine Domain und ein Test
- Füge deine eigene Domain im Dashboard des Hosts hinzu und lege den DNS-Eintrag an, den er verlangt. Zertifikate für HTTPS stellt der Host aus, sobald der Eintrag auflöst.
- Lade zum Schluss die Startseite, einen Deep Link und eine nicht vorhandene Seite. Bei den ersten beiden soll die App erscheinen, bei der dritten eine echte Seite für nicht gefundene Inhalte.
SPA-Rewrite-Regeln nach Host
Wo die Catch-all-Regel hingehört (laut Dokumentation der Hosts, Oktober 2026)
- Host
- Datei
- Regel
- Vercel
- rewrites: source /(.*) auf destination /index.html
- Netlify
- _redirects oder netlify.toml
- Cloudflare Pages
- Keine
- Automatisch, wenn es keine 404.html auf oberster Ebene gibt
- GitHub Pages
- Nur 404.html
- Keine Rewrite-Regeln; als Workaround index.html nach 404.html kopieren
Netlify-Rewrite in netlify.toml
Dieselbe Regel wie die einzeilige _redirects-Datei. Der Status 200 behält die Adresse bei, die der Besucher angefragt hat.
GitHub-Actions-Workflow für eine Vite-Website
Angepasst aus dem Workflow im Deploy-Guide von Vite (der jede Action auf einen Commit festlegt). Er baut bei jedem Push auf main und veröffentlicht dist. Aktiviere GitHub Actions als Quelle unter Settings, dann Pages.
Importiere das Repository; Vercel erkennt Vite. Lege diese Datei im Projektstamm ab, damit Deep Links die App laden.
Build-Befehl npm run build, Publish-Verzeichnis dist. Speichere diese Zeile als public/_redirects, damit Vite sie nach dist kopiert.
Verbinde das Repository und wähle das Vite-Preset. Solange dist keine 404.html auf oberster Ebene enthält, ist keine Regel nötig, weil Pages dann für unbekannte Pfade den Root-Index ausliefert.
Setze base auf den Namen deines Repositorys, baue mit GitHub Actions und veröffentliche dist. GitHub Pages unterstützt eine eigene 404.html, aber keine Rewrite-Regeln. Ein gängiger Workaround ist daher, index.html nach dem Build nach 404.html zu kopieren; diese Deep Links laden dann mit dem Status 404.
Vercel baut Next.js direkt, daher ist ein statischer Export hier optional. Behalte ihn nur, wenn du überall dieselben Dateien haben möchtest.
Setze das Publish-Verzeichnis auf out. Jede Route hat bereits ihre eigene HTML-Datei, daher ist kein Catch-all-Rewrite nötig.
Verwende npm run build mit dem Output-Verzeichnis out. Der Export enthält eine 404.html, daher liefert Pages diese für fehlende Pfade statt der Startseite aus.
Ein statischer Export ist der einzige Weg, Next.js hier zu betreiben. Wenn die Website unter einem Repository-Pfad liegt, setze basePath passend dazu.
Importiere das Repository und deploye. Vercel ist einer der verifizierten Adapter, die in der Deployment-Dokumentation von Next.js aufgeführt sind.
Netlify betreibt Next.js über eine eigene Integration, die in der Next.js-Dokumentation noch nicht als verifizierter Adapter geführt wird. Prüfe in der Netlify-Dokumentation, ob Funktionen fehlen.
Cloudflare betreibt Next.js auf Workers über eine eigene Integration, ebenfalls noch kein verifizierter Adapter. Folge dem Framework-Guide von Cloudflare statt dem statischen Pages-Ablauf.
Nicht möglich. GitHub Pages liefert nur Dateien aus und kann next start nicht ausführen. Wechsle zu einem statischen Export oder wähle einen Host, der Node.js ausführt.
Vite + React
Statischer Next.js-Export
Vollständige Next.js-App
Vercel
Netlify
Cloudflare Pages
GitHub Pages
Deploy-Rezept-Auswahl
Was hast du gebaut?
Wo soll es laufen?
Alle Kombinationen aus App und Host
Kopieren
Kostenlos starten · Keine Kreditkarte nötig
Verwandt: Ratgeber
- Design-System-Beispiele und ein Live-Styleguide
- Design Tokens erklärt, mit JSON-zu-CSS-Konverter
- Startseite einer Website gestalten
- Entwickler-Portfolio
- Landingpage vs. Website
- Discord-Webhook
- Gefunden - zurzeit nicht indexiert
- DNS-Eintragstypen erklärt, mit Beispielen
Produkt
Für wen
- Für Agenturen
- Für Freelancer
- Für Hosting-Anbieter
- Für SaaS-Plattformen
- Für Start-ups
- Finanzdienstleistungen
- Lösungen für das Gesundheitswesen
Funktionen
Ressourcen
- Blog
- Hilfecenter
- Kostenlose Tools für Unternehmen
- Free UI Components
- Vorlagen
- Vorlagen-Sammlungen
- Website-Beispiele
- Ratgeber
- Vergleiche
- Alternativen
- Die besten
- Testberichte
- Preisübersichten
- Anwendungsfälle
- Glossar und Anleitungen
- Integrationen
- Entwickler
- Benchmark
- Windows App