Veröffentliche deine Astro-Seite auf Cloudflare Pages

Du kannst dein Astro-Projekt auf Cloudflare Pages bereitstellen, einer Plattform für Frontend-Entwickler zur Zusammenarbeit und Bereitstellung statischer (JAMstack) und SSR-Webseiten.

Diese Anleitung enthält:

Wie du über das Cloudflare Pages Dashboard veröffentlichst
Wie man mit Wrangler, dem Cloudflare CLI, veröffentlicht
Wie man eine SSR-Seite mit @astrojs/cloudflare veröffentlicht

Voraussetzungen

Um loszulegen, brauchst du Folgendes:

Ein Cloudflare-Konto. Wenn du noch keins hast, kannst du während des Prozesses ein kostenloses Cloudflare-Konto erstellen.
Dein App-Code wird in ein GitHub oder ein GitLab Repository gepusht.

Wie man eine Website mit Git veröffentlicht

Richte ein neues Projekt auf Cloudflare Pages ein.
Pushe deinen Code in dein Git-Repository (GitHub, GitLab).
Melde dich im Cloudflare-Dashboard an und wähle dein Konto unter Konto-Startseite > Seiten aus.
Wähle Ein neues Projekt erstellen und die Option Git verbinden.
Wähle das Git-Projekt aus, das du einrichten willst, und klicke auf Einrichtung beginnen
Verwende die folgenden Build-Einstellungen:
- Framework-Voreinstellung: Astro
- Build-Befehl: npm run build
- Build-Ausgabeverzeichnis: dist
- Umgebungsvariablen (erweitert): Standardmäßig verwendet Cloudflare Pages Node.js 12.18.0, aber Astro erfordert eine höhere Version. Füge eine Umgebungsvariable mit einem Variablennamen von NODE_VERSION und einem Wert von v16.13.0 oder höher hinzu, um Cloudflare anzuweisen, eine kompatible Node-Version zu verwenden. Alternativ kannst du auch eine .nvmrc-Datei zu deinem Projekt hinzufügen, um eine Node-Version anzugeben.
Klicke auf die Schaltfläche Speichern und bereitstellen.

Wie man eine Website mit Wrangler veröffentlicht

Installiere Wrangler CLI.
Authentifiziere Wrangler mit deinem Cloudflare-Konto mit Wrangler Login.
Führe deinen Build-Befehl aus.
Veröffentliche mit npx wrangler pages publish dist.

# Wrangler CLI installieren
npm install -g wrangler
# Anmeldung beim Cloudflare-Konto über CLI
wrangler login
# Run your build command
npm run build
# Neues Deployment erstellen
npx wrangler pages publish dist

Nachdem du deine Assets hochgeladen hast, gibt dir Wrangler eine Vorschau-URL, mit der du deine Seite überprüfen kannst. Wenn du dich in das Cloudflare Pages Dashboard einloggst, siehst du dein neues Projekt.

Lokale Vorschau mit Wrangler aktivieren

Damit die Vorschau funktioniert, musst du wrangler installieren

pnpm add wrangler --save-dev

Es ist dann möglich, das Vorschauskript zu aktualisieren, um wrangler anstelle des in Astro eingebauten Vorschau-Befehls auszuführen:

"preview": "wrangler pages dev ./dist"

Wie man eine SSR-Seite veröffentlicht

Du kannst eine Astro SSR-Seite für den Einsatz auf Cloudflare Pages mit dem @astrojs/cloudflare adapter erstellen.

Befolge die folgenden Schritte, um den Adapter einzurichten. Du kannst dann eine der beiden oben beschriebenen Methoden anwenden.

Schnelle Installation

Füge den Cloudflare-Adapter hinzu, um SSR in deinem Astro-Projekt mit dem folgenden astro add-Befehl zu aktivieren. Damit installierst du den Adapter und nimmst in einem Schritt die entsprechenden Änderungen an deiner Datei astro.config.mjs vor.

npx astro add cloudflare

Manuelle Installation

Wenn du den Adapter stattdessen lieber manuell installieren möchtest, führe die folgenden zwei Schritte aus:

Füge den Adapter @astrojs/cloudflare mit deinem bevorzugten Paketmanager zu den Abhängigkeiten deines Projekts hinzu. Wenn du npm verwendest oder dir nicht sicher bist, führe dies im Terminal aus:
Terminal-Fenster
```
npm install @astrojs/cloudflare
```

Füge Folgendes zu deiner Datei astro.config.mjs hinzu:

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare()
});

Modi

Derzeit werden zwei Modi bei der Verwendung von Pages Functions mit dem @astrojs/cloudflare Adapter unterstützt.

Erweiterter Modus: Dieser Modus wird verwendet, wenn du deine Funktion im erweiterten Modus ausführen willst, der die _worker.js in dist aufnimmt, oder einen Verzeichnismodus, bei dem Pages den Worker aus einem Funktionsordner im Projektstamm kompiliert.

Wenn kein Modus eingestellt ist, ist der Standardwert Erweitert.
Verzeichnis-Modus: Dieser Modus wird verwendet, wenn du deine Funktion im Verzeichnis-Modus ausführen willst. Das bedeutet, dass der Adapter den clientseitigen Teil deiner App auf die gleiche Weise kompiliert, aber das Worker-Skript in einen Funktions-Ordner im Projektstamm verschiebt. Der Adapter legt in diesem Ordner immer nur eine [[Pfad]].js ab, so dass du zusätzliche Plugins und Seiten-Middleware hinzufügen kannst, die in die Versionskontrolle eingecheckt werden können.
astro.config.mjs
```
export default defineConfig({
  adapter: cloudflare({ mode: "directory" }),
});
```

Seitenfunktionen verwenden

Mit [Seitenfunktionen] (https://developers.cloudflare.com/pages/platform/functions/) kannst du serverseitigen Code ausführen, um dynamische Funktionen zu ermöglichen, ohne einen eigenen Server zu betreiben.

Um loszulegen, erstelle ein Verzeichnis /functions im Stammverzeichnis deines Projekts. Wenn du deine Funktionsdateien in dieses Verzeichnis schreibst, wird automatisch ein Worker mit benutzerdefinierten Funktionen für die vorgegebenen Routen erstellt. Mehr über das Schreiben von Funktionen erfährst du in der Pages Functions Dokumentation.

📚 Lies mehr über SSR in Astro.

Fehlerbehandlung

Wenn du auf Fehler stößt, überprüfe, ob die Version von node, die du lokal verwendest (node -v), mit der Version übereinstimmt, die du in der Umgebungsvariable angibst.

Cloudflare benötigt Node v16.13, eine neuere Version als die Standardversion von Astro, also überprüfe, ob du mindestens v16.13 verwendest.

Die clientseitige Hydratisierung kann aufgrund der Einstellung “Auto Minify” von Cloudflare fehlschlagen. Wenn du in der Konsole die Meldung “Hydration completed but contains mismatches” siehst, stelle sicher, dass du Auto Minify in den Cloudflare-Einstellungen deaktivierst.