Cloudflare Pages: Statischen Blog deployen – 5 Frameworks ohne typische Fehler

Der erste Blog-Artikel ist fertig, Sie klicken auf Deploy. Drei Minuten später zeigt Cloudflare Pages Erfolg – im Browser nur eine leere Seite, in der Konsole unter F12 lauter 404.

Der Frust beim ersten Astro-Deploy: Google liefert widersprüchliche Antworten, nach Stunden stellt sich heraus – Output-Verzeichnis war public, Astro-Default ist dist.

90 % der Deployment-Fehler hängen an zwei Einstellungen: Build-Befehl und Output-Verzeichnis. Dieser Artikel liefert die korrekten Werte für Astro, Hugo, Hexo, Gatsby und Eleventy auf Cloudflare Pages sowie schnelle Hilfe bei leerer Seite und Build-Fehlern. In 10 Minuten vom Git-Repo bis live.

Warum Cloudflare Pages? (Und die Plattform-Änderung 2025)

Zuerst, warum ich Cloudflare Pages für statische Blogs empfehle.

Kostenlos und wirklich schnell. Cloudflare betreibt über 300 Rechenzentren weltweit – Ihr Blog wird automatisch verteilt, Leser überall bekommen schnelle Antworten. Im Vergleich zu GitHub Pages und Vercel finde ich Cloudflare Pages stabiler, besonders aus China. Komplett kostenlos, ohne Traffic- oder Build-Limits.

Git-Deploy ohne Aufwand. GitHub- oder GitLab-Repo verbinden – ab dann baut und deployt Cloudflare bei jedem git push. Pull Requests bekommen Preview-Links – praktisch für Teams.

Kostenloses SSL und Custom Domain. Kein Zertifikats-Gefummel, DNS-Einträge sind in Minuten aktiv.

Eins vorweg: Seit April 2025 setzt Cloudflare stärker auf Workers; Pages ist im Wesentlichen im Wartungsmodus.

Für statische Blogs ändert das wenig. Pages bleibt stabil und reicht für Blog oder Doku ohne komplexes SSR. Workers eignen sich eher für dynamische APIs und Edge-Computing.

Kurz: Für rein statische Blogs Pages nutzen. Server-Features später – dann Workers.

Standard-Konfiguration für 5 Frameworks (Kernkapitel)

Hier die verifizierten Einstellungen – direkt übernehmen.

Schnell-Referenztabelle

Diese Tabelle lohnt sich zum Merken – jede Zeile ist geprüft. Details pro Framework folgen.

Astro-Konfiguration

Astro ist mein aktuelles Lieblings-Framework für statische Blogs – schnell und angenehm zu schreiben.

Standard:

• Build-Befehl: npm run build oder astro build
• Output-Verzeichnis: dist

Bei rein statischem SSG reichen die Defaults. Für SSR: Adapter @astrojs/cloudflare installieren und in astro.config.mjs:

import cloudflare from '@astrojs/cloudflare';
export default {
  output: 'server',
  adapter: cloudflare()
};

Custom Output-Verzeichnis (z. B. build) in der Config:

export default {
  outDir: 'build'
};

Ich empfehle dist – weniger Verwirrung im Team.

Hugo-Konfiguration (am fehleranfälligsten)

Bei Hugo stolpern die meisten – mein erster Hugo-Deploy kostete einen Abend.

Standard:

• Build-Befehl: hugo oder hugo -b $CF_PAGES_URL
• Output-Verzeichnis: public
• Umgebungsvariable (Pflicht): HUGO_VERSION = 0.143.1 (oder benötigte Version)

Cloudflare Pages nutzt standardmäßig Hugo 0.54 – von 2019! Die meisten Themes brauchen 0.80+, oft 0.120+. Ohne HUGO_VERSION scheitert das Deploy.

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

15 % Rabatt sichern →Anzeige

Umgebungsvariable unter Settings > Environment variables:

• Name: HUGO_VERSION
• Wert: 0.143.1 (exakt, nicht 0.143)

Bei .pages.dev-Domain (ohne Custom Domain) Build-Befehl:

hugo -b $CF_PAGES_URL

$CF_PAGES_URL setzt Cloudflare automatisch – interne Links, RSS und Sitemap funktionieren.

Hexo-Konfiguration

Hexo ist etabliert, die Konfiguration meist unkompliziert.

Standard:

• Build-Befehl: hexo generate (Kurzform hexo g)
• Output-Verzeichnis: public

Selten Probleme; manche Themes/Plugins brauchen bestimmte Node-Version:

• Name: NODE_VERSION
• Wert: 14.3 oder 18.17.0

Lokal node -v, in Cloudflare Pages denselben Wert setzen.

Gatsby-Konfiguration

Gatsby ist am unkompliziertesten.

Standard:

• Build-Befehl: gatsby build
• Output-Verzeichnis: public

Keine Extras nötig. Mehrere Gatsby-Blogs deployt – ohne Probleme.

Eleventy-Konfiguration

Eleventy (11ty) ist leichtgewichtig und einfach.

Standard:

• Build-Befehl: npx @11ty/eleventy
• Output-Verzeichnis: _site (mit Unterstrich)

Nicht site schreiben – sonst fehlen Dateien.

Custom Output in .eleventy.js:

module.exports = function(eleventyConfig) {
  return {
    dir: {
      output: "public"
    }
  };
};

Next.js-Konfiguration (Neuerung 2025)

Next.js-Blogs: 2025 wichtige Änderung.

Standard (neues Schema):

• Build-Befehl: npx opennextjs-cloudflare
• Output-Verzeichnis: .worker-next

Wichtig: @cloudflare/next-on-pages ist deprecated. Cloudflare empfiehlt @opennextjs/cloudflare.

Alte Tutorials zu next-on-pages ignorieren. Neues Setup:

1. npm install @opennextjs/cloudflare
2. Build: npx opennextjs-cloudflare
3. Output: .worker-next

Für rein statische Blogs rate ich eher zu Astro oder Hugo – Next.js lohnt sich bei dynamischen Features.

Praxis: Vom Git-Repo bis live (Schritt für Schritt)

Konfiguration klar – jetzt deployen. Etwa 10 Minuten.

Vorbereitung

Drei Punkte prüfen:

1. Code auf GitHub oder GitLab – Repo-Seite, neuester Stand
2. package.json (Node.js) – Abhängigkeiten eingetragen, nicht nur lokal installiert
3. .gitignore – node_modules, dist, public usw. ausgeschlossen

Wer node_modules mit pusht, bekommt Deploy-Konflikte. .gitignore prüfen.

Deploy-Schritte im Detail

Schritt 1: Cloudflare Pages öffnen

dash.cloudflare.com – anmelden (kostenlose Registrierung).

Links Workers & Pages, oben rechts Create application.

Schritt 2: Mit Git verbinden

Zwei Optionen:

• Connect to Git – automatisches Deploy (diese Option)
• Direct Upload – manuell (nicht empfohlen)

Connect to Git, dann GitHub oder GitLab.

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

Jetzt starten →Anzeige

Schritt 3: Autorisieren

Erstes Mal: Cloudflare braucht Repo-Zugriff. Sign in → GitHub/GitLab-Autorisierung.

Berechtigungen: Statt aller Repos Only select repositories wählen.

Schritt 4: Repository wählen

Blog-Projekt in der Liste. Nicht sichtbar? Aktualisieren oder Autorisierung wiederholen.

Schritt 5: Build-Einstellungen (entscheidend!)

• Project name: Teil der .pages.dev-Domain, z. B. my-blog → my-blog.pages.dev
• Production branch: meist main oder master
• Framework preset: Framework oder None

Build settings – Konfigurationstabelle:

• Build command
  • Astro: npm run build
  • Hugo: hugo oder hugo -b $CF_PAGES_URL
  • Hexo: hexo generate
  • Gatsby: gatsby build
  • Eleventy: npx @11ty/eleventy
  • Next.js: npx opennextjs-cloudflare
• Build output directory
  • Astro: dist
  • Hugo: public
  • Hexo: public
  • Gatsby: public
  • Eleventy: _site
  • Next.js: .worker-next

Framework preset füllt teils Defaults ein – manuell prüfen.

Schritt 6: Umgebungsvariablen (falls nötig)

Environment variables (advanced) → Add variable.

• Hugo (Pflicht):
  • Name: HUGO_VERSION
  • Wert: 0.143.1 (exakt drei Stellen)
• Hexo (falls nötig):
  • Name: NODE_VERSION
  • Wert: 14.3 oder 18.17.0

Schritt 7: Speichern und deployen

Save and Deploy. Build-Log live – meist 1–3 Minuten.

Schritt 8: Ergebnis

Bei Erfolg: „Success! Your site is live!“ und Link projektname.pages.dev.

Umgebungsvariablen nachträglich

Nicht beim ersten Deploy gesetzt oder geändert:

1. Cloudflare Pages-Projekt
2. Settings
3. Environment variables
4. Add variable
5. Name und Wert → Save

Häufige Variablen:

• HUGO_VERSION: z. B. 0.143.1
• NODE_VERSION: z. B. 18.17.0
• CF_PAGES_URL: automatisch von Cloudflare, für baseURL

Nach Änderung neu deployen: Deployments → letztes Deploy → drei Punkte → Retry deployment.

Preview Deployments

Bei jedem Pull Request erzeugt Cloudflare einen Preview-Link.

PR mit neuem Artikel → Cloudflare baut den Branch → eigene Preview-URL vor dem Merge. Praktisch für Teams.

Probleme? Häufige Fehler und Debugging

Drei typische Fälle – decken etwa 95 % ab.

Problem 1: Build fehlgeschlagen (Building Failed)

Symptome: Deploy hängt bei Building, dann Build failed, rotes Icon.

Zuerst Log lesen, nicht blind neu deployen.

Schritte:

1. Build-Log
   • View build log oder Deployment details
   • Nach unten scrollen, rote Meldung
   • Letzte Zeilen sind entscheidend
2. Build-Befehl
   • Settings > Build & deployments
   • Mit Konfigurationstabelle abgleichen
   • Häufig: npm build statt npm run build
3. Abhängigkeiten
   • „Cannot find module“ oder „Command not found“
   • Paket in package.json? Lokal installiert, aber nicht mit npm install --save?
4. Framework-Version
   • Hugo: fast immer fehlende HUGO_VERSION
     • Log: „Theme requires Hugo Extended version“
     • HUGO_VERSION = 0.143.1 setzen
   • Hexo: Node-Version
     • NODE_VERSION = 18.17.0 (oder lokal)

Fall: Hugo-Blog eines Freundes – Log „Hugo version 0.54.0 does not support this theme“. HUGO_VERSION = 0.120.0 → Deploy ok.

Problem 2: Leere Seite (am häufigsten)

Symptome: Deploy ok, Seite leer, F12 voller 404.

In 90 % der Fälle: falsches Output-Verzeichnis.

Schritte:

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

Jetzt testen →Anzeige

1. F12 – DevTools
   • Console: Fehler
   • Network: Refresh, 404-Ressourcen
   • Sources: Dateistruktur
2. Output-Verzeichnis (~90 %)
   • Settings > Build & deployments
   • Build output directory
   • Typisch:
     • Astro: public statt dist
     • Hugo: dist statt public
     • Eleventy: site statt _site
3. baseURL / publicPath
   • Subpath (z. B. example.com/blog): baseURL
   • Hugo: hugo -b $CF_PAGES_URL
   • Astro: base: '/blog' in astro.config.mjs
   • Vue/React: ggf. publicPath: './'
4. Routing (SPA)
   • Vue/React Router history: Refresh → 404
   • Lösung: Hash-Modus oder _redirects:

     /* /index.html 200

Fall: Eigenes Astro-Deploy – Output war public, mit dist behoben.

Problem 3: Styles oder Assets laden nicht

Symptome: Inhalt da, Layout kaputt, Bilder fehlen.

Schritte:

1. Network in DevTools
   • CSS, JS, Bilder 404?
   • Request-Pfade korrekt?
2. Asset-Pfade
   • Absolut /assets/style.css bei Subpath-Deploy problematisch
   • Framework-Hilfen nutzen:
     • Astro: import
     • Hugo: .RelPermalink oder absURL
     • Hexo: url_for()
3. Externe CDN
   • jsDelivr, cdnjs erreichbar?
   • Ggf. andere CDN

Fall: Hexo-Blog auf Subpath – CSS unter /css/, erwartet /blog/css/. _config.yml: root: /blog/, neu generieren.

Schnell-Checkliste

1. ✓ Build-Log lesen
2. ✓ Build-Befehl (Tabelle)
3. ✓ Output-Verzeichnis (Tabelle)
4. ✓ Umgebungsvariablen (Hugo: HUGO_VERSION)
5. ✓ F12: Console und Network
6. ✓ .gitignore – keine Build-Artefakte im Repo
7. ✓ Lokal npm run build / hugo – funktioniert es?

Sonst: Cloudflare-Community oder offizielle Troubleshooting-Doku.

Fortgeschritten: Professioneller Blog

Live ist der Anfang. Ein paar einfache Verbesserungen:

Custom Domain

.pages.dev geht – eigene Domain wirkt professioneller. Cloudflare liefert kostenlos SSL.

Schritte:

1. Domain beim Registrar (GoDaddy, Alibaba Cloud, Tencent Cloud …)
2. Pages-Projekt → Custom domains
3. Set up a custom domain, z. B. blog.example.com
4. DNS-Einträge vom Registrar übernehmen
5. DNS-Propagation (Minuten bis Stunden)
6. HTTPS automatisch

Tipp: Domain bereits bei Cloudflare → schnellere DNS, oft ohne manuelle Einträge.

Build beschleunigen

Viele Artikel → lange Builds:

1. Caching
   • Pages cached standardmäßig node_modules
   • Jeder Build lädt Dependencies neu? prüfen
2. Weniger Dependencies
   • Unbenutzte Pakete aus package.json
   • CDN-taugliche Libs nicht lokal bundeln
3. Parallel / Cache
   • Hugo: --gc für Cache-Cleanup
   • Astro: experimental.contentCollectionCache
4. Branch-Strategie
   • Arbeit auf dev, Merge nach main nur für Releases
   • Nicht jeder Commit triggert Production-Build

Analytics und Performance

Analytics:

1. Pages-Projekt → Analytics
2. Requests, Bandwidth, Länder, Trends

Web Vitals:

• Ladezeit, Interaktionslatenz
• Schwache Werte → Bilder komprimieren, Lazy Loading

Automatisierung

Mit GitHub Actions z. B.:

• Geplante Veröffentlichung
• Sitemap nach Deploy
• Bildkompression vor Push

Nicht Pflicht – spart Zeit. GitHub Actions + Community-Templates reichen oft.

Fazit

Statischen Blog deployen ist nicht komplex – Build-Befehl und Output-Verzeichnis stimmen, 90 % der Probleme vermeiden.

Kern-Konfiguration noch einmal:

Bei Problemen: Build-Log, dann diese Checkliste – meist reicht das.

Jetzt ausprobieren: Cloudflare Pages, Git verbinden, korrekte Werte eintragen – in 10 Minuten live.

Hat der Artikel geholfen? Teilen Sie ihn mit anderen, die gerade deployen. Fragen in den Kommentaren helfen oft auch anderen.

Viel Erfolg beim Deploy und beim Schreiben!