Worker und Seiten: Bereitstellung, Routing und was jedes Modell verbirgt

Wenn ein Team Cloudflare Workers übernimmt, ist die erste Bereitstellung trivial: wrangler deploy, das war's, das Skript ist live. Wenn ein anderes Team Pages übernimmt, ist die erste Bereitstellung ebenfalls trivial: GitHub-Repository verbinden, Build-Befehl konfigurieren, fertig. Das Problem tritt auf, wenn die beiden in derselben Zone koexistieren, wenn Sie eine Vorschau pro Zweig benötigen oder wenn jemand prüfen muss, was in der Produktion ausgeführt wird, ohne auf das Dashboard zuzugreifen.

Wie Mitarbeiter eingesetzt werden

Das zentrale Artefakt eines Workers-Projekts ist wrangler.toml. Es enthält Routen, Bindungen, Umgebungsvariablen, Kompatibilitätsgrenzen und Umgebungen. Eine typische Produktions-/Staging-Bereitstellung sieht in derselben Datei wie folgt aus:

name = "minha-api"
main = "src/index.ts"
compatibility_date = "2024-09-23"

[[routes]]
pattern = "api.exemplo.com/*"
zone_name = "exemplo.com"

[env.staging]
name = "minha-api-staging"
[[env.staging.routes]]
pattern = "api-staging.exemplo.com/*"
zone_name = "exemplo.com"

Dabei handelt es sich um eine versionierte Konfiguration im Code, die in Pull-Requests überprüft und im Git-Verlauf nachvollzogen werden kann. Jede Routen- oder Bindungsänderung durchläuft denselben Codeüberprüfungsprozess.

wrangler deploy --env staging stellt das Skript als separaten Worker (minha-api-staging) mit eigenen Routen und Bindungen bereit. Umgebungen in Workers sind unterschiedliche Worker – keine Varianten derselben Bereitstellung.

Wie Pages bereitgestellt wird

Pages funktioniert über Git Push. Sie verbinden ein Repository, definieren den Build-Befehl und das Ausgabeverzeichnis im Dashboard und jeder Push an den Hauptzweig löst eine Pipeline aus: Klonen, Installieren, Erstellen, Hochladen der Assets in das CDN. Die Pipeline läuft bis zu 500 Builds/Monat beim kostenlosen Plan und 5.000/Monat beim kostenpflichtigen Plan (20 $/Monat).

Der große betriebliche Unterschied: Jeder Push an einen anderen Zweig als den Hauptzweig generiert eine automatische Vorschaubereitstellung mit einer eindeutigen URL im Format hash-branch.seuprojet.pages.dev. Sie öffnen einen Pull-Request, Cloudflare kommentiert die PR mit der Vorschau-URL. Das Produktteam testet die URL, bevor es die Zusammenführung genehmigt. Workers hat dafür kein natives Äquivalent.

Die symmetrische Einschränkung: Die Build-Einstellungen für Seiten – Build-Befehl, Umgebungsvariablen, Knotenversion – befinden sich im Dashboard und nicht in der Codedatei. Bisher gibt es keine vollständige wrangler.toml-Unterstützung für Pages. Dies bedeutet, dass Änderungen an der Build-Konfiguration nicht über Pull-Requests erfolgen und nicht im Git-Verlauf gespeichert werden. Für Teams, die einen vollständigen Prüfpfad für die Infrastruktur benötigen, stellt dies eine echte Hürde dar.

Routing und die Routenkollisionsfalle

Arbeiter verwenden Routenmuster, die mit einer Zone verknüpft sind. Das Muster api.exemplo.com/v1/* erfasst alle Anfragen für diesen Pfad und liefert sie an das entsprechende Skript. Wenn zwei verschiedene Worker versuchen, dasselbe Muster in derselben Zone zu registrieren, schlägt die zweite Bereitstellung mit einem Konfliktfehler fehl.

Pages verwendet eine dedizierte Subdomain (*.pages.dev) oder eine benutzerdefinierte Domain, die mit dem Projekt verknüpft ist. Wenn Sie eine benutzerdefinierte Domäne in Pages verwenden, erstellt Cloudflare einen internen Worker, der die Assets bereitstellt und sie an die Funktionen weiterleitet. Dieser interne Worker belegt die Domänenrouten.

Das konkrete Problem: Sie haben ein Pages-Projekt in app.exemplo.com und möchten einen separaten Worker hinzufügen, um Webhooks in app.exemplo.com/webhooks zu verarbeiten. Es gibt nicht. Seitenrouten erfassen bereits app.exemplo.com/*. Die Lösung besteht darin, den Webhooks-Handler in eine Pages-Funktion in /functions/webhooks.ts zu verschieben oder eine separate Subdomäne (webhooks.exemplo.com) mit einem unabhängigen Worker zu verwenden.

Die Routing-Priorität innerhalb von Pages folgt einer festen Reihenfolge: _redirects wird zuerst verarbeitet, dann _headers, dann die Funktionen in /functions und zuletzt die statischen Assets. Das bedeutet, dass eine Funktion in /functions/blog/[slug].ts Vorrang vor einer statischen Datei in /blog/qualquer-coisa.html hat – was überraschend sein könnte, wenn Sie statische Seiten mit demselben Pfad generiert haben.

Seitenumgebungen und was fehlt

Pages verfügt über das Konzept von Produktions- und Vorschauumgebungen. Die Produktion ist der Hauptzweig; Jeder andere Zweig generiert eine Vorschau. Sie können Umgebungsvariablen getrennt nach Umgebung im Dashboard konfigurieren.

Was Pages nicht bietet: mehrere benannte Umgebungen mit unterschiedlichen Build-Konfigurationen. Workers erlaubt wrangler deploy --env staging mit einem völlig anderen Satz von Bindungen und Variablen. Wenn Sie in Pages eine Staging-Umgebung mit einer anderen D1-Datenbank wünschen, erstellen Sie ein separates Pages-Projekt und verwalten die Synchronisierung zwischen beiden manuell.

Für Teams, die mit striktem Staging arbeiten – [separate Datenbank, Sandbox-API-Schlüssel, unterschiedliche Funktionsflags] – ist diese Einschränkung erheblich und verlagert diese Arbeitslasten im Allgemeinen auf die Mitarbeiter.

Wie wrangler.toml (teilweise) zu Pages gelangt

Cloudflare kündigte im Jahr 2020 experimentelle Unterstützung für die Konfiguration von Pages Functions-Bindungen an – KV-Namespaces, D1-Datenbanken, Umgebungsvariablen. Dies löst einen Teil des Audit-Trail-Problems: Die Bindungen bleiben im Code. Die Build-Pipeline (Befehl, Ausgabeverzeichnis, Knotenversion) befindet sich jedoch weiterhin im Dashboard.

Der aktuelle Zustand ist unvollständig. Diejenigen, die heute eine 100-prozentige Codekonfiguration benötigen, verwenden Workers mit Assets, die über die R2 + Cache-API bereitgestellt werden, und verzichten auf das kostenlose Pages-CDN. Dies ist ein echter Kompromiss, den es wert ist, vor der Entscheidung durchgerechnet zu werden.

Was ist vor der Entscheidung zu bewerten?

Das Pages-Bereitstellungsmodell bietet zwei konkrete Vorteile: integrierte Build-Pipeline (kein externes CI zum Zusammenstellen) und automatische Vorschau-Bereitstellungen pro Zweig. Für Design- und Produktteams, die Funktionen vor dem Zusammenführen überprüfen, beschleunigt die Zweigvorschau den Überprüfungszyklus messbar.

Workers bietet vom ersten Tag an überprüfbare Codekonfigurationen, benannte Umgebungen mit unterschiedlichen Bindungen und Unterstützung für Nicht-HTTP-Trigger (Cron, Warteschlangen, E-Mail), die Pages nicht bietet. Bei APIs oder Diensten ohne visuelle Komponente, die eine strenge Bereitstellung erfordern, sind Workers mit gut organisierten wrangler.toml-Strukturen operativ sauberer.

Routenkollisionen zwischen Projekten in derselben Zone sind das häufigste Problem für Teams, die mit Pages beginnen und dann versuchen, isolierte Worker hinzuzufügen. Die richtige mentale Zuordnung: Eine benutzerdefinierte Domäne in Pages ist wie ein Worker, der den Platzhalter dieser Domäne belegt. Alles andere, was Sie in dieser Domain wünschen, muss im Pages-Projekt enthalten sein.