Cloudflare Pages Deployment: React/Vue/Next.js Konfiguration und Fehlerbehebung

Einleitung

Sie haben Ihr React-Projekt fertig und wollen es online stellen – dann öffnen Sie die Cloudflare Pages-Konfiguration und starren auf „Build Command” und „Build Output Directory”. Was eintragen? npm run build oder npm build? Output-Verzeichnis build oder dist? Wie setzen Sie Umgebungsvariablen?

Dieser Artikel führt Sie Schritt für Schritt durch das Deployment von React-, Vue- und Next.js-Projekten auf Cloudflare Pages: vollständige Konfigurations-Checkliste, Umgebungsvariablen und Lösungen für 5 häufige Fehler – besonders der Next.js-nodejs_compat-Fehler.

Warum Cloudflare Pages?

Vielleicht fragen Sie sich: Es gibt schon Vercel und Netlify – warum Cloudflare Pages?

Ich habe anfangs auch Vercel genutzt. Nicht, weil Vercel schlecht wäre – aber das Free-Tier hat Grenzen. Mehrere kleine Projekte zusammen überschritten schnell 100 GB/Monat, und Vercel begann zu drosseln.

Nach dem Vergleich der drei Plattformen zeigte sich: Cloudflare Pages im Free-Tier ist wirklich attraktiv:

Unbegrenzter Traffic ist besonders überzeugend. Mehrere persönliche Projekte laufen bei mir auf CF Pages – ohne Traffic-Sorgen.

Geeignete Szenarien:

• Persönliche Blogs, Portfolio-Websites
• Mittelgroße Frontend-Projekte (SPA, statische Sites)
• Projekte mit globalem CDN-Bedarf
• Projekte mit unklarem Traffic-Volumen (unbegrenzter kostenloser Traffic)

Weniger geeignet:

• Große Next.js-Apps mit komplexem SSR (CF Pages unterstützt Next.js weniger umfassend als Vercel)
• Projekte mit häufigen Builds (500 Builds/Monat Limit)
• Projekte, die Vercel-spezifische Features brauchen (z. B. Edge Middleware)

Vorbereitung vor dem Deployment

Bevor Sie starten, brauchen Sie:

1. Cloudflare-Konto registrieren
   • Auf der Cloudflare-Website registrieren (kostenlos)
   • E-Mail verifizieren – dann kann es losgehen
2. Code-Repository vorbereiten
   • Code auf GitHub oder GitLab pushen
   • CF Pages holt den Code direkt aus Ihrem Git-Repository
3. Build-Konfiguration Ihres Projekts kennen
   • Create React App oder Vite?
   • Build-Befehl? (meist npm run build)
   • Build-Ausgabe-Verzeichnis? (CRA: build, Vite: dist)

Vorbereitung abgeschlossen – los geht’s mit dem praktischen Deployment.

React-App: vollständiger Deployment-Workflow

React ist eines der am häufigsten genutzten Frontend-Frameworks. Ich habe mehrere React-Projekte auf CF Pages deployed – hier die bewährte Konfigurations-Checkliste.

Schnell ein React-Projekt erstellen (falls noch keins vorhanden)

Wenn Sie mitmachen wollen, aber kein Projekt haben:

# Methode 1: Vite (empfohlen, schnellerer Build)
npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install
# Methode 2: Create React App (klassisch)
npx create-react-app my-react-app
cd my-react-app

Ich empfehle Vite – deutlich schnellerer Build. CRA wird bei großen Projekten langsam.

Cloudflare Pages Konfigurations-Checkliste

Cloudflare Dashboard öffnen, zu Pages navigieren, „Projekt erstellen” → „Mit Git verbinden”, GitHub-Repository wählen.

Dann erscheint die Konfigurationsseite – hier liegt der Schlüssel:

Konfigurationsübersicht:

Hinweise:

• Vite: Framework preset „None” reicht – CF Pages erkennt automatisch
• CRA: Preset „Create React App” wählen – Konfiguration wird automatisch ausgefüllt
• Output-Verzeichnis ist die häufigste Fehlerquelle: Vite → dist, CRA → build – nicht vertauschen!

Umgebungsvariablen setzen

React-Projekte haben eine Besonderheit: Umgebungsvariablen brauchen ein spezifisches Präfix für Client-Zugriff.

Vite-Projekte:

• Präfix muss VITE_ sein
• Beispiele: VITE_API_URL, VITE_API_KEY

CRA-Projekte:

• Präfix muss REACT_APP_ sein
• Beispiele: REACT_APP_API_URL, REACT_APP_API_KEY

Setzen:

1. In Cloudflare Pages (empfohlen):
   • Projekt → Settings → Environment variables
   • „Add variable” klicken
   • Umgebung wählen: Production oder Preview
   • Variablenname und Wert eingeben
2. Im Code verwenden:

// Vite-Projekt
const apiUrl = import.meta.env.VITE_API_URL;
// CRA-Projekt
const apiUrl = process.env.REACT_APP_API_URL;

Lokale Entwicklung:

.env.local im Projektroot erstellen:

# Vite-Projekt
VITE_API_URL=https://api.example.com
VITE_API_KEY=your-api-key-here
# CRA-Projekt
REACT_APP_API_URL=https://api.example.com
REACT_APP_API_KEY=your-api-key-here

Wichtig:

• .env.local nicht in Git committen! In .gitignore: .env*.local
• Nach Änderung an Umgebungsvariablen: neues Deployment auslösen

SPA-Routing-404 beheben

Bei React Router kann ein Seiten-Refresh nach Deployment 404 auslösen.

Grund: SPA-Routen müssen auf index.html zeigen, der Server sucht aber die entsprechende Datei.

Lösung:

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

_redirects-Datei im public-Verzeichnis erstellen:

/* /index.html 200

Diese eine Zeile leitet alle Pfade auf index.html um und gibt Status 200 zurück.

Nach erneutem Deployment funktioniert das Routing.

Deployment-Erfolg prüfen

Nach „Save and Deploy” startet CF Pages den Build. Fortschritt unter „Deployments” im Build-Log verfolgen.

Erfolgszeichen:

• Log zeigt „Success: Deployed to…”
• Link xxx.pages.dev wird bereitgestellt
• Projekt ist erreichbar

Bei Build-Fehler:

• Log auf Fehlermeldungen prüfen
• Häufige Ursachen:
  • Falsches Output-Verzeichnis (Vite als build oder CRA als dist)
  • Node-Version zu alt (Umgebungsvariable NODE_VERSION=18 setzen)
  • Abhängigkeiten-Installation fehlgeschlagen (package.json prüfen)

Vue-App: vollständiger Deployment-Workflow

Vue-Deployment ähnelt React, hat aber einige Besonderheiten.

Schnell ein Vue-Projekt erstellen (optional)

# Methode 1: Vite (empfohlen)
npm create vite@latest my-vue-app -- --template vue
cd my-vue-app
npm install
# Methode 2: Vue CLI
vue create my-vue-app
cd my-vue-app

Auch hier empfehle ich Vite – bessere Performance.

Cloudflare Pages Konfigurations-Checkliste

Wichtig:

• Vue CLI und Vite nutzen beide dist (anders als React)
• Umgebungsvariablen-Präfixe unterscheiden sich: Vite → VITE_, Vue CLI → VUE_APP_

Umgebungsvariablen setzen

Vite + Vue:

# .env.local
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=My Vue App

Vue CLI:

# .env.production
VUE_APP_API_BASE_URL=https://api.example.com
VUE_APP_TITLE=My Vue App

Im Code:

// Vite-Projekt
const apiUrl = import.meta.env.VITE_API_BASE_URL;
// Vue CLI-Projekt
const apiUrl = process.env.VUE_APP_API_BASE_URL;

Vue Router-Konfiguration

Bei Vue Router, besonders History-Modus, Redirect konfigurieren – sonst 404 beim Refresh.

Methode 1: _redirects-Datei (empfohlen)

_redirects im public-Verzeichnis:

/* /index.html 200

Methode 2: vite.config.js (Vite-Projekte)

Bei Deployment außerhalb des Root-Verzeichnisses base setzen:

// vite.config.js
export default {
  base: '/', // Root-Pfad sicherstellen
}

Häufige Probleme

Problem 1: Statische Assets 404

publicPath oder base in vue.config.js (Vue CLI) oder vite.config.js (Vite) prüfen:

// vue.config.js (Vue CLI)
module.exports = {
  publicPath: '/', // Root-Pfad sicherstellen
}

Problem 2: Vite-Build-Fehler „Unknown file extension”

Meist zu alte Node-Version. In CF Pages Umgebungsvariable setzen:

NODE_VERSION=18

Dann erneut deployen.

Next.js-App: vollständiger Deployment-Workflow (Schwerpunkt!)

Next.js auf Cloudflare Pages ist ehrlich gesagt das komplexeste der drei Frameworks. Beim ersten Deployment hat mich der nodejs_compat-Fehler einen halben Tag gekostet.

Wenn Ihr Next.js-Projekt viel SSR braucht, empfehle ich Vercel. Für statische Sites oder einfaches SSR reicht CF Pages vollkommen – und unbegrenzter kostenloser Traffic ist unschlagbar.

Besonderheiten bei Next.js-Deployment

Vor dem Start wichtig zu wissen:

1. Cloudflare Pages ist nicht speziell für Next.js konzipiert (anders als Vercel) – zusätzliche Konfiguration nötig
2. Zwei Deployment-Wege: statischer Export (einfachste) und SSR-Modus (Adapter erforderlich)
3. Für SSR: @opennextjs/cloudflare-Adapter (alter @cloudflare/next-on-pages ist deprecated)

Methode 1: Statischer Export (einfachste, für Einsteiger)

Wenn Ihr Next.js-Projekt kein serverseitiges Rendering, API Routes oder ISR braucht, ist statischer Export der einfachste Weg.

Geeignet für:

• Persönliche Blogs
• Dokumentations-Sites
• Reine Präsentations-Websites
• Projekte ohne dynamische Daten

Konfigurationsschritte:

1. next.config.js anpassen:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // Schlüssel: statischen Export aktivieren
  images: {
    unoptimized: true, // CF Pages unterstützt kein Next.js Image Optimization
  },
}
module.exports = nextConfig

2. Cloudflare Pages-Konfiguration:

3. Deployment:

Konfiguration speichern und deployen. Nach erfolgreichem Build erhalten Sie eine statische Site.

Einschränkungen:

• ❌ Keine API Routes
• ❌ Kein ISR (Incremental Static Regeneration)
• ❌ Keine Server Components
• ❌ Kein serverseitiges Rendering dynamischer Routen

Wenn Sie diese Einschränkungen akzeptieren, reicht statischer Export vollkommen.

Methode 2: SSR-Modus (mit OpenNext-Adapter)

Für API Routes, SSR und dynamische Routen brauchen Sie einen Adapter. Etwas komplexer – aber ich erkläre es Schritt für Schritt.

Adapter installieren:

npm install @opennextjs/cloudflare

next.config.js konfigurieren:

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Kein output: 'export' setzen
  images: {
    unoptimized: true,
  },
}
module.exports = nextConfig

Cloudflare Pages-Konfiguration:

Wichtig! Compatibility Flags setzen (häufigste Fehlerquelle):

Dieser Schritt ist entscheidend – viele scheitern hier. Beim ersten Deployment fehlte mir das Flag, und ich bekam dauerhaft nodejs_compat is not defined.

1. Projekt → Settings → Functions
2. Compatibility flags finden
3. Configure Production compatibility flag klicken
4. Flag hinzufügen: nodejs_compat
5. Compatibility Date: mindestens 2024-09-23 (oder neuer)

Achtung:

• Production und Preview müssen beide konfiguriert werden
• Ohne dieses Flag: 500-Fehler nach Deployment

Edge Runtime-Anforderung:

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

Bei API Routes oder Server Components Edge Runtime deklarieren:

// app/api/hello/route.js
export const runtime = 'edge'; // Schlüssel! Diese Zeile erforderlich
export async function GET(request) {
  return new Response(JSON.stringify({ message: 'Hello from CF Pages' }), {
    headers: { 'content-type': 'application/json' },
  });
}

// pages/api/hello.js (Pages Router)
export const config = {
  runtime: 'edge', // Schlüssel! Diese Zeile erforderlich
};
export default function handler(req) {
  return new Response(JSON.stringify({ message: 'Hello from CF Pages' }), {
    headers: { 'content-type': 'application/json' },
  });
}

Alle serverseitig ausgeführten Dateien brauchen diese Deklaration – sonst schlägt das Deployment fehl.

Next.js Umgebungsvariablen

Next.js unterscheidet zwei Arten:

1. Client-Variablen (Präfix erforderlich):

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_SITE_NAME=My Next.js Site

2. Server-Variablen (kein Präfix):

# .env.local
DATABASE_URL=postgresql://...
API_SECRET=your-secret-key

In Cloudflare Pages setzen:

Settings → Environment variables, Umgebung wählen (Production/Preview).

Im Code:

// Client
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
// Server (API Route oder Server Component)
const dbUrl = process.env.DATABASE_URL;

Next.js: häufige Fehler und Lösungen (Schwerpunkt!)

Fünf häufigste Fehler aus eigener Erfahrung:

Fehler 1: nodejs_compat is not defined oder 500-Fehler

Fehlermeldung:

Error: The global scope does not support nodejs_compat

Oder Deployment erfolgreich, aber Seite zeigt 500.

Ursache:

Fehlendes nodejs_compat Compatibility Flag.

Lösung:

1. Projekt → Settings → Functions
2. Compatibility flags finden
3. In Production und Preview nodejs_compat hinzufügen
4. Erneut deployen

Das hat mich lange aufgehalten – nach dem Setzen war es sofort behoben.

Fehler 2: Deployment erfolgreich, Seite zeigt 404

Symptome:

• Build-Log zeigt Erfolg
• xxx.pages.dev zeigt 404
• Oder nur Startseite erreichbar, andere Seiten 404

Ursache:

• Edge Runtime nicht korrekt konfiguriert
• Oder falsches Build output directory

Lösung:

1. Prüfen, ob alle API Routes und Server Components runtime = 'edge' haben
2. Build output directory: .worker-next (Adapter) oder out (statischer Export)
3. Bei statischem Export: _redirects-Datei prüfen

Fehler 3: FinalizationRegistry is not defined

Fehlermeldung:

ReferenceError: FinalizationRegistry is not defined

Ursache:

Compatibility Date zu alt – neue JavaScript-Features nicht unterstützt.

Lösung:

1. Settings → Functions
2. Compatibility Date auf 2024-09-23 oder neuer setzen
3. Erneut deployen

Fehler 4: Build dauert zu lange oder schlägt fehl

Symptome:

• Build läuft über 10 Minuten
• Oder „Build exceeded maximum duration”

Ursache:

• Turbopack genutzt (next dev --turbo)
• Oder Projekt zu groß, zu viele Abhängigkeiten

Lösung:

1. Build command prüfen: npx @opennextjs/cloudflare, kein --turbo
2. Unnötige Abhängigkeiten entfernen: npm prune
3. Statischen Export in Betracht ziehen (falls möglich)

Fehler 5: Image Optimization-Fehler

Fehlermeldung:

Error: Image Optimization using Next.js' default loader is not compatible with `output: 'export'`.

Ursache:

Cloudflare Pages unterstützt die Next.js Image Optimization API nicht.

Lösung:

In next.config.js deaktivieren:

module.exports = {
  images: {
    unoptimized: true,
  },
}

Für Bildoptimierung alternativ:

• Cloudflare Images (kostenpflichtig)
• Drittanbieter-CDN (z. B. Cloudinary)
• Bilder vor dem Upload selbst komprimieren

Umgebungsvariablen: Fortgeschritten

Umgebungsvariablen verwirren anfangs – besonders der Unterschied zwischen Dev, Preview und Production. Hier eine klare Verwaltungsmethode.

Drei Umgebungen unterscheiden

Cloudflare Pages unterstützt drei Umgebungen:

Im Cloudflare Dashboard setzen

Projekt → Settings → Environment variables

Zwei Tabs:

• Production: Produktions-Umgebungsvariablen
• Preview: Preview-Umgebungsvariablen

Empfohlene Konfiguration:

1. Production-Variablen (echte API Keys, DB-Verbindungen):
   • Typ Secret (verschlüsselt, nicht im Log sichtbar)
   • Beispiel: API_KEY=prod-key-12345
2. Preview-Variablen (Test-API Keys):
   • Plain text möglich
   • Beispiel: API_KEY=test-key-67890

Lokale Entwicklung

Empfohlene Dateistruktur:

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

my-project/
├── .env.local          # Lokale Variablen (nicht in Git)
├── .env.example        # Vorlage (in Git)
├── .gitignore          # Sensible Dateien ignorieren

.env.local-Beispiel:

# API-Konfiguration
VITE_API_BASE_URL=http://localhost:3000/api
VITE_API_KEY=local-dev-key
# Feature-Flags
VITE_ENABLE_DEBUG=true
VITE_ENABLE_ANALYTICS=false
# Drittanbieter-Dienste
VITE_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

.env.example-Beispiel:

# API-Konfiguration
VITE_API_BASE_URL=your-api-url-here
VITE_API_KEY=your-api-key-here
# Feature-Flags
VITE_ENABLE_DEBUG=false
VITE_ENABLE_ANALYTICS=true

Wichtig:

• .env.local nicht in Git committen
• .env.example in Git für Team-Referenz
• In .gitignore: .env*.local

Umgebungsvariablen-Präfixe: Schnellreferenz

Merksatz:

• Browser-Zugriff → Präfix erforderlich
• Nur Server (API Key, DB-Passwort) → kein Präfix

Umgebungsvariablen greifen nicht – Debugging

Checkliste aus eigener Erfahrung:

Debugging-Schritte:

1. Präfix prüfen
   • Vite-Projekt mit REACT_APP_-Präfix? (sollte VITE_ sein)
   • Next.js Client-Variable ohne NEXT_PUBLIC_?
2. Neues Deployment auslösen
   • Nach Änderung muss ein neues Deployment laufen
   • Kleinen Git-Push oder im Dashboard „Retry deployment” klicken
3. Richtige Umgebung prüfen
   • Production-Variablen geändert, aber Preview-URL aufgerufen?
   • Oder umgekehrt?
4. Build-Log prüfen
   • Variablennamen im Log suchen
   • Secret-Variablen zeigen keinen Wert
5. Referenz im Code prüfen

   // ❌ Falsch (Vite-Projekt)
   const apiUrl = process.env.VITE_API_URL;
   // ✅ Richtig (Vite-Projekt)
   const apiUrl = import.meta.env.VITE_API_URL;

Fortgeschrittene Tipps und Best Practices

Deployment ist nur der Anfang – diese Tipps machen Ihr Projekt professioneller.

Eigene Domain binden

xxx.pages.dev wirkt weniger professionell – eigene Domain binden ist einfach.

Schritte:

1. Domain in Cloudflare Pages hinzufügen:
   • Projekt → Custom domains
   • Set up a custom domain klicken
   • Domain eingeben (z. B. blog.example.com)
2. DNS-Eintrag konfigurieren:
   • Domain bereits bei Cloudflare: CNAME wird automatisch hinzugefügt
   • Domain bei anderem Anbieter: manuell hinzufügen:

     CNAME  blog  your-project.pages.dev

3. Auf SSL-Zertifikat warten:
   • Cloudflare stellt kostenloses SSL-Zertifikat aus
   • Meist 5–10 Minuten

Dann erreichen Sie Ihre Site über die eigene Domain – mit automatischem HTTPS.

Preview Deployments

Besonders nützlich für Teams. Bei Push auf Nicht-Main-Branches oder Pull Requests erstellt CF Pages automatisch eine Preview-Umgebung.

So funktioniert’s:

1. Neuen Branch erstellen:

   git checkout -b feature/new-button

2. Code ändern und pushen:

   git add .
   git commit -m "Add new button"
   git push origin feature/new-button

3. CF Pages baut automatisch und generiert Preview-Link:

   https://abc123.your-project.pages.dev

4. Preview-Link im PR prüfen, neues Feature testen
5. Nach Merge auf main: automatisches Production-Deployment

Vorteile:

• Jeder Feature-Branch hat eigene Preview-Umgebung
• Product Manager und Designer können direkt testen
• Production bleibt unberührt

Build-Cache optimieren

Wenn Builds langsam sind, Cache optimieren.

Cache-Konfiguration:

Cloudflare Pages cached node_modules automatisch – weitere Optimierung möglich:

1. pnpm nutzen (schneller als npm):

   # .npmrc im Projekt
   echo "package-manager=pnpm" > .npmrc

2. In CF Pages setzen:
   • Build command: pnpm install && pnpm build
3. Unnötige Abhängigkeiten entfernen:

   npm prune

Nach Umstieg auf pnpm sank die Build-Zeit von 5 auf 2 Minuten – spürbarer Unterschied.

Custom Headers konfigurieren

Für eigene HTTP Headers (Sicherheitsrichtlinien, Cache-Steuerung) _headers-Datei im Projektroot erstellen:

# _headers-Beispiel
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: no-referrer-when-downgrade
/static/*
  Cache-Control: public, max-age=31536000, immutable
/api/*
  Cache-Control: no-cache

Nach erneutem Deployment sind die Headers aktiv.

Zusammenfassung

Kernpunkte in drei Sätzen:

1. Build-Konfiguration Ihres Projekts kennen

• Build command? (meist npm run build)
• Output-Verzeichnis? (Vite → dist, CRA → build, Next.js je nach Modus)
• Welche Umgebungsvariablen? (Präfix beachten)

2. Häufige Fallstricke beachten

• Next.js nodejs_compat-Flag (ohne → 500-Fehler)
• Umgebungsvariablen-Präfixe (Vite → VITE_, Next.js → NEXT_PUBLIC_)
• SPA-Routing-404 (_redirects-Datei nicht vergessen)

3. Preview-Umgebung nutzen

• Nicht direkt in Production testen
• Feature-Branches mit Preview testen
• Erst nach erfolgreichem Test auf main mergen

Cloudflare Pages ist nicht schwer – der erste Setup-Aufwand lohnt sich. Danach: Git Push, automatisches Deployment, fertig.

Unbegrenzter kostenloser Traffic ist unschlagbar – mehrere persönliche Projekte laufen bei mir auf CF Pages, ohne Traffic-Sorgen.

Bei Problemen:

• Zuerst den Abschnitt „Häufige Fehler” in diesem Artikel prüfen
• Build-Log lesen – Fehlermeldungen zeigen die Ursache
• Offizielle Dokumentation: Cloudflare Pages Docs

Nächste Schritte:

• Erstes Projekt auf Cloudflare Pages deployen
• Eigene Domain binden
• Preview Deployments ausprobieren

Bei Fragen gerne in den Kommentaren – ich antworte. Viel Erfolg beim Deployment!