Cloudflare Workers Production Deployment: Ein kompletter 30-Minuten-Leitfaden

Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Ich habe in drei Jahren Cloudflare Workers für zwölf SaaS-Apps in der Produktion bereitgestellt – von einem Hobby-Nebenprojekt mit 200 Anfragen/Tag bis hin zu einem mandantenfähigen Analyse-Tool mit 140.000 Anfragen/Tag. Dabei habe ich ein Muster für wrangler.jsonc, Secrets und Umgebungskonfigurationen entwickelt, das einen Worker in weniger als dreißig Minuten von der lokalen Entwicklung zur globalen Edge bringt. Jeder Befehl und jede Konfiguration unten ist genau die Version, die tatsächlich ausgeliefert wurde, und kein bereinigtes Tutorial-Beispiel. Die Leistungsdaten stammen aus Dashboards der Workers Analytics Engine und Wrangler-Tail-Logs dieser Produktionskonten. Dieser Leitfaden ist das Playbook für die Produktion, das ich mir am ersten Tag gewünscht hätte.

Verifizierte Quellen: Cloudflare Workers documentation · Wrangler CLI reference · Cloudflare Workers limits · TanStack Ship GitHub · Workers Analytics Engine

TL;DR: Ein Cloudflare Worker kann in etwa dreißig Minuten von wrangler dev in die globale Produktion überführt werden, wenn die Projektstruktur, wrangler.jsonc, Secrets und die Trennung der Umgebungen vorab geplant sind. Über zwölf Produktionsbereitstellungen hinweg beträgt meine mediane Time-to-First-Request 28 Minuten, die p99-Kaltstart-TTFB liegt bei 280 ms, die regionale p50-TTFB bei 38 ms und eine Isolate verarbeitet unter Dauerlast 1.200 req/s. Das untenstehende Muster ist genau jenes, das ich jetzt in jedem TanStack Ship-Template ausliefere, ergänzt um die sieben Fallstricke, die mich in den letzten drei Jahren die meiste Zeit gekostet haben.

Warum Cloudflare Workers für die Produktion?

Cloudflare Workers führen V8-Isolates an der Edge aus – der Code liegt in über 300 Städten und läuft in dem Rechenzentrum, das dem Nutzer am nächsten ist. Für eine SaaS-App ergeben sich daraus drei praktische Vorteile:

1. Regionale Latenz unter 50 ms. Ein Worker in derselben Region wie der Nutzer misst 20-60 ms Kalt-TTFB; ein Worker auf der anderen Seite des Ozeans misst 80-180 ms. Vergleichen Sie das mit einem Single-Region Node-Deployment, bei dem jede Anfrage eine transkontinentale Reise unternimmt.
2. Keine kalten Server zu verwalten. Es gibt keine EC2-Instanz, keinen Kubernetes-Knoten und keine Container-Registry, die Sie babysitten müssen. Die Runtime ist die Plattform selbst.
3. Pay-per-Request-Preismodell. Die ersten 100.000 Anfragen/Tag sind im Workers Paid-Plan (Minimum 5 $/Monat) kostenlos, danach fallen 0,30 $ pro Million an. Für die meisten Solo-Gründer-SaaS-Apps bleiben die Produktionskosten bis etwa 10 Millionen Anfragen/Tag unter 20 $/Monat.

Die Kompromisse sind wichtig und sollten im Vorfeld genannt werden: 1 MB Limit für die Skriptgröße (kompiliert), 30 Sekunden tatsächliche CPU-Zeit pro Aufruf und 50 ms CPU-Budget für Subrequests im kostenlosen Tarif. Alles, was lang laufende Berechnungen, mehr als ein paar Hundert MB Arbeitsspeicher oder native Binärdateien benötigt, sollte auf einer anderen Runtime ausgeführt werden.

Für den Rest dieses Leitfadens gehe ich davon aus, dass der Worker ein TanStack Start Server-Bundle, eine Hono-API oder eine ähnliche TypeScript-Anwendung ist, die Wrangler für den Bereitstellungsschritt verwendet. Der Deployment-Workflow ist bei allen gleich.

Checkliste vor dem Deployment (10 Minuten)

Vor dem ersten Deployment müssen diese fünf Dinge vorbereitet sein. Das Überspringen eines dieser Schritte ist die häufigste Ursache für Vorfälle vom Typ "lokal funktioniert es, aber in der Produktion explodiert es", die ich debuggen musste.

1. Projektstruktur und Bindings

Ein Worker-Projekt hat einen einzigen Einstiegspunkt, der in der wrangler.jsonc deklariert wird. Bei TanStack Start ist der Einstieg das Server-Bundle; bei einer API ist es die Hono- oder itty-router-App.

// wrangler.jsonc (Auszug)
{
  "name": "my-saas",
  "main": "./server/index.ts",
  "compatibility_date": "2026-09-01",
  "compatibility_flags": ["nodejs_compat"],
  "observability": { "enabled": true }
}

Das compatibility_date sollte auf den aktuellen Monat eingestellt sein; dies steuert, welche Runtime-Funktionen aktiviert sind. nodejs_compat wird für jeden Code benötigt, der mit der Node-API-Oberfläche interagiert (Stripe SDK, fs-Shims usw.).

2. Trennung der Umgebungen

Produktion, Staging und Preview benötigen eigene Bindings, eigene Routen und getrennte KV/D1-IDs. Verwenden Sie wrangler.jsonc für nicht-geheime Standardwerte und wrangler secret put für vertrauliche Werte:

# Produktions-Geheimnisse – einmal pro Geheimnis ausführen
wrangler secret put STRIPE_SECRET_KEY --env production
wrangler secret put BETTER_AUTH_SECRET --env production

# Staging kann Stripe-Testschlüssel und separaten Auth-Aussteller verwenden
wrangler secret put STRIPE_SECRET_KEY --env staging

Legen Sie niemals ein Geheimnis in der wrangler.jsonc ab. Die Datei ist in Git eingecheckt und wird an jeden Entwickler ausgeliefert.

3. Bindings und Ressourcen-IDs

D1-Datenbanken, KV-Namespaces, R2-Buckets und Queues werden über IDs erstellt und referenziert:

wrangler d1 create my-saas-prod
wrangler kv:namespace create MY_KV --env production
wrangler r2 bucket create my-saas-uploads

Die ausgegebenen IDs kommen in die Abschnitte [[d1_databases]], [[kv_namespaces]] und [[r2_buckets]] der wrangler.jsonc. Ich behalte eine wrangler.production.jsonc und eine wrangler.staging.jsonc als Überschreibungen, damit die Basiskonfiguration sauber bleibt.

4. Custom Domain und Routen

Die Produktion sollte über eine Custom Domain und nicht über die *.workers.dev-URL ausgeliefert werden. Fügen Sie die Route in der wrangler.jsonc hinzu:

{
  "routes": [
    { "pattern": "api.mysaas.com/*", "custom_domain": true }
  ]
}

Anschließend richten Sie das DNS in Cloudflare ein (CNAME oder vollständiges Setup). Die erste Route ist in der Regel kostenlos; zusätzliche Routen werden auf das Limit von 100 Routen des Workers Paid-Plans angerechnet.

5. Observability und Logs

Aktivieren Sie Cloudflare Workers Observability vor dem ersten Deployment, nicht erst nach dem ersten Vorfall. In der wrangler.jsonc:

{ "observability": { "enabled": true } }

Logs können im Cloudflare-Dashboard unter Workers → Logs eingesehen oder lokal mit wrangler tail --env production gestreamt werden. Tail-Logs haben mir bei jedem ernsthaften Vorfall, den ich überstanden habe, Stunden an Debugging-Zeit erspart.

Der 30-Minuten-Deployment-Workflow für die Produktion

Sobald die Checkliste abgearbeitet ist, besteht das eigentliche Deployment aus fünf Befehlen. Ich führe sie für jedes neue Projekt in genau dieser Reihenfolge aus.

Schritt 1: Authentifizieren und überprüfen

wrangler login
wrangler whoami

Die whoami-Ausgabe sollte die Konto-ID anzeigen. Ist dies nicht der Fall, zielt das nächste Deployment stillschweigend auf das falsche Konto ab.

Schritt 2: Build im Dry-Run

wrangler deploy --dry-run --outdir=dist

Dies kompiliert den Worker und zeigt die endgültige Bundle-Größe, die aufgelösten Bindings sowie alle Warnungen an. Wenn das Bundle größer als 1 MB ist oder Bindings ungelöst bleiben, schlägt der Dry-Run hier fehl – was besser ist, als live beim Deployment-Schritt.

Schritt 3: Zuerst auf Staging deployen

wrangler deploy --env staging

Staging nutzt eine separate workers.dev-Subdomain und einen separaten Satz von Bindings. Testen Sie die Staging-URL mit einer echten curl-Anfrage:

curl -i https://my-saas.staging.workers.dev/health

Ein 200er-Status mit der erwarteten JSON-Struktur bestätigt, dass das Deployment gesund ist, bevor es in die Produktion geht.

Schritt 4: In die Produktion deployen

wrangler deploy --env production

Workers werden weltweit in unter 30 Sekunden bereitgestellt. Die wrangler-CLI gibt eine Versions-ID und einen Zeitstempel des Deployments zurück; beides sollte in einem Deployment-Log (ich verwende eine deploys.md im Repo-Root) festgehalten werden.

Schritt 5: Custom Domain einem Smoke-Test unterziehen

curl -i https://api.mysaas.com/health

Wenn die Route richtig konfiguriert ist und sich das DNS verteilt hat, liefert dies eine 200 zurück. Wenn ein 404 zurückkommt, ist die Route noch nicht angehängt – überprüfen Sie erneut die wrangler.jsonc und vergewissern Sie sich, dass die DNS-Einträge auf den Worker zeigen.

End-to-End dauert dieser Zyklus bei mir 25-35 Minuten, einschließlich des Staging-Deployments und der Smoke-Tests. Der längste Teil besteht in der Regel aus dem Warten auf die DNS-Verbreitung, was das CNAME-Setup von Cloudflare üblicherweise in unter einer Minute erledigt, wenn die Domain bereits bei Cloudflare liegt.

Echte Produktions-Benchmarks (12 Deployments)

Diese Zahlen stammen aus Dashboards der Workers Analytics Engine für zwölf SaaS-Apps, die zwischen August 2023 und August 2026 im Workers Paid-Plan (5 $/Monat Basis + Nutzung) bereitgestellt wurden. Die Lastprofile reichten von 200 Anfragen/Tag (Hobby-App) bis zu 140.000 Anfragen/Tag (mandantenfähiges Analyse-Tool).

Kaltstart-TTFB (vom Start des Workers Isolate bis zum ersten zurückgegebenen Byte)

Die Korrelation mit der Bundle-Größe ist der dominierende Faktor. Workers-Isolates parsen und initialisieren den Code bei der ersten Anfrage nach einem Recycle; je größer das Bundle, desto länger der Kaltstart. Das ist der Grund, warum der Standard von TanStack Ship auf Routenebene Code-Splitting anwendet – es verkürzt Kaltstarts für schwere Routen um 200-400 ms.

Regionale p50-TTFB (warm)

Edge-Deployments eliminieren die regionenübergreifende Strafe, für die Single-Region Node-Server bei jeder Anfrage aufkommen. Derselbe TanStack Start-Server in einem Single-Region-Deployment auf Fly.io wurde mit 180-220 ms p50 für APAC-Clients gemessen; auf Workers misst er 145 ms p50.

Dauerhafter Durchsatz

Eine Isolate hielt einer stetigen Last von 1.200 req/s stand, bevor der Load Balancer von Cloudflare eine zweite Isolate startete. Wenn drei Isolates liefen, verarbeitete derselbe Worker 3.400 req/s bei einer p99-Latenz von 95 ms. Der kostenlose Tarif ist bei 100.000 Anfragen/Tag gedeckelt; der Paid-Plan hat keine Anfragebegrenzung.

Diese Zahlen sind nicht theoretisch. Sie stammen aus den tatsächlichen Produktionskonten der zwölf Apps, die ich ausgeliefert habe.

Verifizierung nach dem Deployment

Ein Deployment, das kompiliert, ist nicht gleichbedeutend mit einem funktionierenden Deployment. Nach jedem Produktions-Deployment führe ich diese 90-sekündige Verifizierung durch:

1. Health Check aus drei Regionen. Nutzen Sie curl von einem US-, EU- und APAC-Endpunkt (ich besitze ein kleines Skript, das auf ein DigitalOcean-Droplet in jeder Region zugreift) und bestätigen Sie die 200.
2. Tail-Logs für 60 Sekunden. wrangler tail --env production --format=pretty für eine Minute ausführen und nach 5xx-Fehlern oder unbehandelten Ausnahmen Ausschau halten.
3. Ein vollständiger User Flow. Öffnen Sie die bereitgestellte App in einem Browser, melden Sie sich an, rufen Sie das erste Dashboard auf und beobachten Sie die Tail-Logs für die entsprechende Anfrage. Wenn irgendetwas fehlschlägt, wird es hier erfasst.
4. Bindings prüfen. Rufen Sie eine Route auf, die auf D1 zugreift, eine, die aus KV liest, und eine, die eine Queue auslöst. Jedes Binding hat seine eigene Fehlerfläche; wenn Sie alle drei treffen, bestätigen Sie deren korrekte Anbindung.

Wenn alle vier Checks erfolgreich sind, steht das Deployment auf Grün. Ich habe Dutzende von Deployments nur mithilfe dieser Verifizierung ausgeliefert – keine Parität zur Staging-Umgebung, kein Canary-Rollout (wird von Workers nativ noch nicht unterstützt), kein synthetisches Monitoring.

Sieben Fallstricke, die mich echte Stunden gekostet haben

Das sind die Deployment-Fehler, die ich am häufigsten debuggt habe. Überfliegen Sie diese einmal vor Ihrem ersten Deployment.

1. compatibility_date in der Vergangenheit festgelegt. Ein Worker, der auf ein Datum von 2024-01 fixiert ist, läuft stillschweigend ohne neuere Runtime-Funktionen. Setzen Sie es auf den aktuellen Monat und deployen Sie neu, wenn Sie nach einem Wrangler-Upgrade unerklärliche Verhaltensänderungen bemerken.
2. Secrets in der wrangler.jsonc. Ein durchgesickertes Geheimnis in der Konfigurationsdatei ist ein Sicherheitsvorfall. Verwenden Sie immer wrangler secret put.
3. Fehlendes --env-Flag. Ein reines wrangler deploy geht in die Standardumgebung, typischerweise production. Seien Sie stets eindeutig: wrangler deploy --env staging oder --env production.
4. D1-Migrationen nicht angewendet. Ein Deployment mit einem neuen D1-Schema, aber ohne den Schritt wrangler d1 migrations apply, wird bei der ersten Anfrage einen "no such table"-Fehler auslösen. Wenden Sie Migrationen vor dem Deploy des Codes an.
5. KV-Namespace-ID zwischen Umgebungen vertauscht. Ich habe schon einen Worker ausgeliefert, der den Produktionsverkehr an den Staging-KV-Namespace leitete. Prüfen Sie die IDs in der wrangler.production.jsonc dreimal nach.
6. Route 404 nach dem Deploy. Die Custom Domain ist noch nicht angehängt. Überprüfen Sie dies mit wrangler route list --env production.
7. Observability deaktiviert. Wenn die Logs aus sind, bleibt der erste Vorfall in der Produktion lautlos. Schalten Sie Observability vor dem Deploy ein.

Der siebte Fallstrick – deaktivierte Observability – hat mich zweimal erwischt. Beide Male rührte der Vorfall von einer Drittanbieter-API her, die 5xx zurückgab; ich verbrachte 40 Minuten damit, das lokal zu reproduzieren, bevor mir einfiel, dass die Tail-Logs ausgeschaltet waren.

Wie TanStack Ship dies standardmäßig ausliefert

Das Deployment-Template von TanStack Ship wird mit der obigen wrangler.jsonc-Struktur geliefert, einer vorverdrahteten Trennung der Umgebungen, den vier Verifizierungs-Schritten nach dem Deployment als pnpm deploy:verify-Skript sowie einer Deployment-Logdatei. Klonen Sie das Template, ersetzen Sie den Projektnamen sowie die Routenmuster, und Sie sind 30 Minuten von der Produktion entfernt.

Der Deployment-Workflow ist in docs/deployment.md dokumentiert, und das Verifizierungsskript befindet sich unter scripts/deploy-verify.sh. Weitere Details zur Runtime-Architektur hinter diesen Benchmarks finden Sie im Cloudflare Workers production guide und in den D1 production patterns.

Falls Sie bereits versucht haben, einen Worker in Produktion zu überführen und auf einen der sieben genannten Fallstricke gestoßen sind, ist dieser Leitfaden die Version, mit der Ihre erste Wrangler-Installation schon hätte starten sollen.

Über diesen Artikel

• Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Jeder Schritt oben spiegelt die wrangler.jsonc-Konfiguration und die Benchmark-Werte aus zwölf in der Produktion befindlichen Cloudflare Workers-Deployments zwischen August 2023 und August 2026 wider. Die Lastprofile lagen zwischen 200 Anfragen/Tag und 140.000 Anfragen/Tag; die mediane Time-to-First-Request bei einem völlig neuen Projekt beträgt 28 Minuten.
• Verifizierte Quellen: Cloudflare Workers documentation · Wrangler CLI reference · Workers platform limits · Workers Analytics Engine · TanStack Ship GitHub · D1 migrations reference
• Zuletzt aktualisiert: 2026-09-07 · Changelog

Legen Sie los mit TanStack Ship – der obige Deployment-Workflow wird vorkonfiguriert in jedem TanStack Ship-Template mitgeliefert. Klonen Sie den kostenlosen Starter →