Das Hosting auf Cloudflare Pages ermöglicht es Frontend-Teams, Code schnell, sicher und ohne Serveradministration bereitzustellen. Durch die Nutzung von Cloudflare Pages erhalten Entwickler eine leistungsstarke, Edge-native Plattform zur Bereitstellung statischer Webanwendungen, Single-Page-Apps (SPAs) und Server-Side-Rendered-Frameworks (SSR). Durch die direkte Anbindung an Ihr Git-Repository automatisiert Cloudflare Build-Pipelines, generiert Preview-Deployments und hostet Assets weltweit. Dieser Leitfaden erklärt, wie Sie Ihr Git-Repository verbinden, Build-Einstellungen konfigurieren, benutzerdefinierte Domains einrichten und Weiterleitungen einrichten.

Zusammenfassung:

  • Edge-native Frontend-Apps bereitstellen; Cloudflare Pages liefert Assets weltweit über das Cloudflare-Netzwerk aus, was Ladezeiten im Subsekundenbereich garantiert.
  • Git-Integration automatisieren; verknüpfen Sie Ihr Repository, um automatische Builds auszulösen und Preview-URLs für jeden Commit zu generieren.
  • Framework-Build-Einstellungen konfigurieren; legen Sie Ausgabeordner und Befehle für React, Vue, Next.js, Hugo oder Astro fest.
  • Weiterleitungs- und Header-Regeln anwenden mit einfachen Textdateien (_redirects und _headers) in Ihrem öffentlichen Ordner.
  • Benutzerdefinierte Domains zuweisen mit kostenlosen, automatisch erneuerten SSL-Zertifikaten, die von Cloudflare verwaltet werden.

Was ist Cloudflare Pages?

Cloudflare Pages ist eine serverlose Hosting-Plattform für Frontend-Entwickler, ähnlich wie Netlify oder Vercel, die direkt auf der globalen Infrastruktur von Cloudflare aufbaut.

Anstatt Dateien auf einem einzelnen Cloud-Server zu hosten, verteilt Cloudflare Pages Ihre HTML-, CSS-, JavaScript-Dateien und Bilder auf Edge-Standorte weltweit. Wenn ein Benutzer Ihre Website aufruft, werden die Assets vom nächstgelegenen Standort bereitgestellt, was die Netzwerklatenz minimiert. Für Projekte, die serverseitige Logik erfordern, lässt sich Pages mit Cloudflare Workers integrieren, um Backend-Funktionen auszuführen. Um Pages mit anderen Edge-Computing-Diensten zu vergleichen, lesen Sie unseren Leitfaden zu Cloudflare Pages vs. Workers .

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass folgende Punkte erfüllt sind:

  • Ein Git-Repository auf GitHub oder GitLab, das Ihr Projekt enthält (oder die erstellten Dateien bereit für einen direkten Upload).
  • Ein Framework, das statische Assets ausgibt – React (Vite), Vue, Astro, SvelteKit, Hugo oder einfaches HTML. Serverseitig gerenderte Frameworks funktionieren ebenfalls über Pages Functions.
  • Ein funktionierender lokaler Build. Führen Sie Ihren Build-Befehl aus (z.B. npm run build) und bestätigen Sie, dass der Ausgabeordner ohne Fehler generiert wird.
  • Ein kostenloses Cloudflare-Konto. Für den kostenlosen Tarif ist keine Kreditkarte erforderlich.
  • Node.js lokal installiert (empfohlen), damit Sie Builds reproduzieren und das Wrangler-Kommandozeilenwerkzeug verwenden können.

Ein schneller Test spart Stunden bei der Fehlersuche: Wenn Ihre Website auf Ihrem eigenen Rechner nicht sauber gebaut werden kann, wird dies auch auf den Build-Runnern von Cloudflare fehlschlagen. Beheben Sie lokale Fehler zuerst.

Schritt 1: Verbinden Ihres Git-Repositorys

Melden Sie sich zunächst in Ihrem Cloudflare-Dashboard an, navigieren Sie zu Compute > Pages und klicken Sie auf Projekt erstellen.

Wählen Sie Mit Git verbinden, um Ihr GitHub- oder GitLab-Konto zu verknüpfen. Wählen Sie das Repository aus, das Ihre statische Webanwendung enthält. Diese Integration ist wertvoll, da sie eine Continuous Integration (CI)-Pipeline etabliert: Jedes Mal, wenn Sie Code in Ihren Produktions-Branch pushen, baut und veröffentlicht Cloudflare die Updates automatisch. Für andere Commits generiert Cloudflare eindeutige „Preview-URLs“, sodass Sie Änderungen vor dem Zusammenführen testen können.

Schritt 2: Konfigurieren der Build-Einstellungen

Cloudflare Pages unterstützt gängige statische Seitengeneratoren und Frontend-Frameworks. Konfigurieren Sie während des Einrichtungsassistenten die folgenden Einstellungen basierend auf Ihrem Stack:

  • Build-Befehl: Das in Ihrer package.json definierte Build-Skript (z.B. npm run build oder hugo --minify).
  • Build-Ausgabeordner: Der Ordner, der die kompilierte statische Website enthält (z.B. dist, build oder public).
  • Umgebungsvariablen: Wenn Ihr Build-Skript API-Schlüssel oder Konfigurationsvariablen benötigt, definieren Sie diese hier.

Cloudflare erkennt viele Frameworks automatisch, aber das Bestätigen der Voreinstellung vermeidet einen fehlgeschlagenen ersten Build. Typische Kombinationen sind:

FrameworkBuild-BefehlAusgabeordner
React (Vite)npm run builddist
React (Create React App)npm run buildbuild
Next.js (statischer Export)npx next buildout
Astronpm run builddist
Vue (Vite)npm run builddist
SvelteKitnpm run build.svelte-kit/cloudflare
Hugohugo --minifypublic

Legen Sie Ihre Node-Version fest. Eine häufige Ursache dafür, dass ein Build lokal funktioniert, aber auf Cloudflare fehlschlägt, ist eine Diskrepanz zwischen der standardmäßigen Node-Version des Build-Runners und der von Ihrem Projekt erwarteten Version. Deklarieren Sie diese explizit, entweder als Umgebungsvariable im Dashboard:

1NODE_VERSION = 20

Oder indem Sie eine .node-version-Datei im Repository-Root committen:

120

Schritt 3: Einrichten von Weiterleitungen und Headern

Für Single-Page-Apps (wie React Router) oder Migrationen alter URLs müssen Sie Routing- und Weiterleitungsregeln konfigurieren. Pages verarbeitet dies über einfache Textdateien, die in Ihrem Ausgabeordner platziert werden.

Weiterleitungen (_redirects)

Erstellen Sie eine Datei namens _redirects in Ihrem öffentlichen Ordner (public). Damit eine React-SPA das clientseitige Routing sauber verarbeitet, fügen Sie die folgende Fallback-Regel hinzu:

1/*  /index.html  200

Dies zwingt alle Anfragen dazu, auf die index.html aufzulösen, sodass der JavaScript-Router den Pfad verwalten kann.

Die Reihenfolge ist wichtig. Cloudflare wertet die Regeln von oben nach unten aus und stoppt beim ersten Treffer. Spezifische Weiterleitungen müssen daher über dem Catch-All-Fallback stehen:

1# Permanent redirect for a moved page
2/old-pricing   /pricing            301
3
4# Redirect an entire section, preserving the sub-path
5/blog/*        /articles/:splat    301
6
7# SPA fallback (must come last)
8/*             /index.html         200

Der Platzhalter :splat überträgt den übereinstimmenden Teil des Pfads an das Ziel. Der kostenlose Tarif erlaubt bis zu 2.000 statische Weiterleitungsregeln pro Projekt. Wenn Sie mehr benötigen, verschieben Sie die Logik in eine Pages-Funktion oder nutzen Sie Bulk Redirects.

Benutzerdefinierte Header (_headers)

Erstellen Sie eine Datei namens _headers, um Sicherheitsregeln, Referrer-Policies oder benutzerdefinierte Cache-Steuerungen anzuwenden:

1/*
2  X-Frame-Options: DENY
3  X-Content-Type-Options: nosniff
4  Referrer-Policy: strict-origin-when-cross-origin

Diese Datei ist auch der richtige Ort, um das Caching zu optimieren. Mit Hashes versehene, unveränderliche Assets können ein Jahr lang gecacht werden, während HTML-Dateien frisch bleiben sollten, damit Benutzer immer den neuesten Build erhalten:

1/assets/*
2  Cache-Control: public, max-age=31536000, immutable

Um zu sehen, wie sich diese Regeln im Vergleich zu traditionellem Backend-Routing verhalten, lesen Sie Erstellung einer serverlosen API mit Cloudflare Workers .

Schritt 4: Zuweisen benutzerdefinierter Domains

Nach der Bereitstellung stellt Cloudflare eine Standard-Subdomain zur Verfügung (z.B. ihr-projekt.pages.dev).

Um Ihre benutzerdefinierte Domain zuzuweisen, navigieren Sie in Ihrem Pages-Projekt zum Tab Custom Domains und geben Sie Ihre Domain ein (z.B. ihrunternehmen.de). Wenn Ihre DNS-Verwaltung bei Cloudflare liegt, konfiguriert die Plattform die CNAME-Einträge und stellt automatisch ein kostenloses, sich selbst erneuerndes SSL-Zertifikat bereit. Wenn Sie Unterstützung bei der Domainzuweisung, DNS-Verwaltung oder Serversicherheit benötigen, besuchen Sie unsere Seite zur Sicherheitsprüfung von Websites .

Schritt 5: Bereitstellung mit der Wrangler CLI (Direkter Upload)

Die Git-Integration ist für die meisten Teams ideal, aber Sie können mit Wrangler, dem Kommandozeilenwerkzeug von Cloudflare, auch direkt von Ihrem Rechner oder aus einer bestehenden Pipeline heraus veröffentlichen. Dies ist nützlich, wenn Ihr Build bereits in GitHub Actions oder GitLab CI läuft und Sie nur das fertige Ergebnis hochladen möchten.

Installieren Sie Wrangler und melden Sie sich an:

1npm install -g wrangler
2wrangler login

Führen Sie den Build lokal aus und laden Sie den Ausgabeordner in ein bestimmtes Projekt hoch:

1npm run build
2wrangler pages deploy ./dist --project-name=my-web-app

Der erste Durchlauf erstellt das Projekt, falls es noch nicht existiert. Ersetzen Sie in der CI das interaktive wrangler login durch ein API-Token, das über eine Umgebungsvariable bereitgestellt wird, sodass kein Browser-Schritt erforderlich ist:

1# .github/workflows/deploy.yml (excerpt)
2- name: Deploy to Cloudflare Pages
3  run: npx wrangler pages deploy ./dist --project-name=my-web-app
4  env:
5    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
6    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Der direkte Upload überspringt den Build-Schritt von Cloudflare. Dies vermeidet Probleme mit der Build-Umgebung und gibt Ihnen die volle Kontrolle über Ihre Toolchain.

Häufige Fehler und Fehlerbehebung

Eine Handvoll Probleme macht den Großteil aller fehlgeschlagenen Erst-Deployments aus:

  • 404-Fehler beim Aktualisieren einer SPA-Route. Eine clientseitige Route wie /dashboard gibt „Nothing is here yet“ zurück, da keine entsprechende Datei auf dem Speicher existiert. Die Lösung ist der /* /index.html 200-Fallback in der _redirects-Datei. Stellen Sie sicher, dass diese Datei im Build-Ausgabeordner und nicht in Ihrem Quellordner landet.
  • _redirects oder _headers werden ignoriert. Diese Dateien müssen im veröffentlichten Ausgabeordner liegen, nicht nur im Repository. Platzieren Sie sie bei Vite, Astro oder SvelteKit im public/- (oder static/)-Ordner, damit sie beim Build unverändert kopiert werden.
  • Build funktioniert lokal, schlägt aber auf Cloudflare fehl. Dies liegt fast immer an einer abweichenden Node-Version oder einer fehlenden Umgebungsvariable für den Build. Legen Sie die Node-Version fest und deklarieren Sie alle Variablen neu, die das Build-Skript benötigt – diese unterscheiden sich von Laufzeit-Bindings.
  • Zu viele Dateien oder zu großes Deployment. Ein einzelnes Deployment ist auf 20.000 Dateien beschränkt, mit einer maximalen Dateigröße von 25 MiB. Große Mediendateien gehören in R2 oder einen externen Bilderdienst, nicht in das statische Bundle.
  • Alte Assets nach einem Release. Mit Hashes versehene Dateien wie app.4f2c.js können aggressiv gecacht werden, index.html hingegen nicht. Halten Sie die HTML-Datei auf einem kurzen Cache und setzen Sie mit Hashes versehene Assets auf unveränderlich (immutable).

Testen und Produktionsaspekte

Cloudflare erstellt für jeden Nicht-Produktions-Branch und jeden Pull Request ein Preview-Deployment, jeweils unter einer eigenen URL (zum Beispiel abc123.my-web-app.pages.dev). Da Previews im selben Edge-Netzwerk wie Ihre Live-Website laufen, sind sie ein zuverlässiger Ort, um Änderungen vor dem Zusammenführen zu überprüfen.

Für echte Releases entscheiden einige Kontrollmechanismen darüber, ob Sie nur einen Hoster oder einen verlässlichen Workflow haben:

  • Rollbacks. Jedes Deployment wird aufbewahrt, sodass ein fehlerhaftes Release rückgängig gemacht werden kann, indem Sie im Dashboard in Sekundenschnelle einen früheren Build wieder in die Produktion hochstufen – ohne erneuten Build.
  • Umgebungstrennung. Legen Sie unterschiedliche Variablen für Produktion und Preview fest, damit Preview-Builds auf Staging-APIs statt auf Live-Daten verweisen.
  • Analytics und Core Web Vitals. Aktivieren Sie Cloudflare Web Analytics – datenschutzfreundlich und ohne Cookies –, um echte LCP-, CLS- und Traffic-Werte von Nutzern zu erfassen, ohne ein Skript von Drittanbietern zu laden.
  • Zugriffskontrolle für Previews. Preview-URLs sind standardmäßig öffentlich. Wenn ein Branch unveröffentlichte Arbeit offenlegt, schützen Sie ihn mit Cloudflare Access, damit nur Ihr Team ihn öffnen kann.

Wenn Sie diese Punkte frühzeitig umsetzen, bleiben Ihre Deployments vorhersehbar, während das Projekt wächst und mehr Personen daran mitarbeiten.

Wichtige Erkenntnisse

  • Cloudflare Pages hostet statische Webanwendungen im globalen Edge-Netzwerk von Cloudflare und optimiert so die Ladezeiten.
  • Automatisieren Sie die Bereitstellung, indem Sie GitHub oder GitLab verknüpfen, um Code bei jedem Commit zu kompilieren.
  • Definieren Sie Build-Befehle und Ausgabeordner passend zu Ihrem Framework (Astro, Next.js, Hugo, React).
  • Konfigurieren Sie Weiterleitungen und Sicherheits-Header mit einfachen _redirects- und _headers-Textdateien in Ihrem Ausgabeordner.
  • Weisen Sie benutzerdefinierte Domains mit kostenlosen, automatisch erneuerten SSL-Zertifikaten direkt über Cloudflare zu.

Optimieren Sie Ihre Webinfrastruktur

Die Bereitstellung schneller, sicherer Frontends erfordert die Wahl der richtigen Hosting-Architektur und Caching-Regeln. Mecanik ist spezialisiert auf Dienstleistungen zur Website-Entwicklung und bietet professionelle Dienstleistungen für technische SEO-Audits . Wir erstellen maßgeschneiderte React-, Next.js- und Astro-Plattformen, die für Core Web Vitals optimiert und auf Cloudflare bereitgestellt werden. Kontaktieren Sie uns noch heute, um Ihr nächstes Projekt zu besprechen.

Häufig gestellte Fragen (FAQ)

Was ist Cloudflare Pages Hosting? Es handelt sich um eine serverlose Frontend-Hosting-Plattform, die statische Webanwendungen, React-SPAs und Ausgaben statischer Seitengeneratoren (wie Astro oder Hugo) weltweit auf dem CDN von Cloudflare erstellt und bereitstellt.

Unterstützt Cloudflare Pages Server-Side Rendering (SSR)? Ja. Pages unterstützt SSR-Frameworks (wie Next.js, Astro, SvelteKit), indem serverseitige Logik während des Build-Prozesses automatisch in serverlose Cloudflare Workers konvertiert wird.

Wie konfiguriere ich Weiterleitungen auf Cloudflare Pages? Sie erstellen eine einfache Textdatei namens _redirects im Build-Ausgabeordner und schreiben dort Weiterleitungsregeln, die den Quellpfad, den Zielpfad und den HTTP-Statuscode definieren.

Ist Cloudflare Pages kostenlos? Ja. Cloudflare Pages bietet einen großzügigen kostenlosen Tarif, der unbegrenzte Deployments, unbegrenzte Bandbreite und benutzerdefinierte Domains umfasst, was es für statisches Hosting äußerst kosteneffizient macht.

Wie richte ich eine benutzerdefinierte Domain auf Pages ein? Navigieren Sie zum Tab „Custom Domains“ in Ihrem Pages-Projektdashboard, geben Sie Ihren Domainnamen ein, und Cloudflare konfiguriert die DNS-Einträge und stellt ein kostenloses SSL-Zertifikat aus.