Szybka odpowiedź: kiedy wdrożyć Astro na Cloudflare Workers i jak skonfigurować bindings?
- Cloudflare Workers wybierz, gdy potrzebujesz renderowania na żądanie albo bindings do KV, R2, D1 czy Durable Objects.
- Czysto statyczna strona nie potrzebuje ani adaptera, ani bindings.
- Zasoby importujesz z
cloudflare:workers, a nie przezAstro.locals.runtime. - Lokalnie Astro działa w
workerd, a zdalne bindings kieruj na środowisko testowe, nie produkcyjne. - Plan darmowy ma limit 10 ms czasu CPU na żądanie.
w Astro dostał bardzo mocną integrację: lokalnie, do KV/R2/D1 bez ręcznych atrap i działający w środowisku na brzegu sieci. To nie jest demo z dokumentacji. To konfiguracja, na której można oprzeć zwykłą stronę produkcyjną.
Dlaczego wybrać Cloudflare Workers dla Astro zamiast Cloudflare Pages
Aktualny adapter Cloudflare dla Astro celuje w Workers. Cloudflare rekomenduje Workers dla nowych projektów, a sam adapter nie wspiera już wdrożeń na Cloudflare Pages. Pages nadal sprawdzają się przy istniejących prostych stronach statycznych, ale nowe projekty, a tym bardziej te z SSR, Server Islands, Actions, Sessions albo bindings, zakładaj od razu na Workers.
Istniejący projekt na Pages? Migracja jest przewidywalna, z racji tego, że Cloudflare przygotował oficjalny przewodnik migracyjny, a większość konfiguracji przenosi się 1:1.
Jak zainstalować adapter Cloudflare w Astro
Standardowa ścieżka:
To instaluje aktualny @astrojs/cloudflare, dodaje do astro.config.mjs odpowiednią konfigurację i pozwala później dopisać wrangler.jsonc, w sytuacji, kiedy potrzebujesz bindings, środowisk albo niestandardowych ustawień Workera.
Po instalacji Twój astro.config.mjs wygląda mniej więcej tak:
Są dwie rzeczy, na które warto zwrócić uwagę:
output: 'server'sprawia, że cały projekt Astro renderuje się na żądanie, na brzegu sieci. Alternatywnie możesz użyć klasycznego'static'(w tym wypadku adapter nie jest potrzebny). Tryb'hybrid'nie istnieje od Astro 5.0, ponieważ został scalony ze'static': domyślnie strony są prerenderowane, a pojedyncze trasy oznaczaszexport const prerender = false, by renderować je na żądanie.imageService: 'cloudflare-binding'oznacza domyślną w aktualnym adapterze transformację obrazów przez Cloudflare Images binding. Alternatywnie użyj'compile'dla optymalizacji w czasie budowania na trasach prerenderowanych albo'passthrough', jeśli masz własny proces obsługi obrazów.
Lokalne środowisko Astro na Cloudflare Workers: workerd zamiast Node
To największa zmiana dla użytkowników Cloudflare po przejściu na nowy adapter. Wcześniej astro dev działał w Node.js, a produkcja w workerd. Teraz lokalne środowisko działa w tym samym workerd co produkcja, więc klasyczny błąd „działa lokalnie, nie działa na produkcji" jest dużo łatwiejszy do złapania przed wdrożeniem.
Pod spodem Astro:
- Bootstrapuje Vite z Cloudflare Vite plugin.
- Uruchamia workerd jako środowisko wykonawcze dla Twojego kodu.
- Zapewnia lokalny dostęp do API platformy (KV, R2, D1, Durable Objects), bez ręcznych atrap.
Skutek jest prosty: kod z cloudflare:workers API działa tak samo w dev i na produkcji. Stary dostęp przez Astro.locals.runtime znika, obejścia przestają być potrzebne, a importy z cloudflare:* działają bezpośrednio w astro dev.
Bindings w Astro na Cloudflare Workers: KV, R2, D1 i Durable Objects
Bindings to sposób, w jaki Worker (i Twoje Astro) łączy się z zasobami Cloudflare: (magazyn klucz-wartość), (przechowywanie plików zgodne z S3), (SQLite), (obliczenia z własnym stanem).
Konfigurujesz je w wrangler.jsonc:
A w kodzie Astro korzystasz z nich przez bezpośredni import z cloudflare:workers:
TypeScript wie o Twoich bindings, więc po uruchomieniu wrangler types w worker-configuration.d.ts pojawiają się typy, które obejmują import env z cloudflare:workers.
Jak typować bindings Cloudflare w projekcie Astro
Nie dopisuj już ręcznie typu Runtime do App.Locals, jeśli używasz aktualnego adaptera. Po zmianie wrangler.jsonc, .dev.vars albo listy bindings uruchamiasz:
Warto podpiąć to pod skrypty projektu:
Teraz env.DB.prepare(...), env.SESSIONS.get(...) albo env.MEDIA.put(...) mają podpowiadanie typów, a TypeScript zgłasza błąd, jeśli próbujesz użyć bindingu, którego nie ma w konfiguracji.
Praca z lokalną bazą D1: migracje, dane i flaga --local
Sam binding to dopiero połowa sukcesu, ponieważ bazę D1 trzeba jeszcze wypełnić schematem i danymi, i tu czeka najczęstsza pułapka. Wrangler (od wersji 3+) domyślnie trzyma dane lokalnie, w odizolowanym storage, oddzielnie od produkcji. To celowe i bezpieczne: lokalna sesja nie ma dostępu do produkcyjnych danych, a dane utrwalają się między kolejnymi uruchomieniami dev servera.
Migracje i zapytania na lokalnej bazie uruchamiasz z flagą --local:
Jeśli lokalna baza „dziwnie" jest pusta po ponownym uruchomieniu, przyczyna prawie zawsze jest ta sama: migracje poszły na niewłaściwą instancję. Sprawdź, czy faktycznie zaaplikowałeś je z flagą --local, a nie na zdalnej bazie albo w innym katalogu projektu. To samo dotyczy seedowania danych testowych, ponieważ jeden plik .sql z danymi startowymi puszczony przez wrangler d1 execute --local --file=./seed.sql daje powtarzalny stan lokalny, który każdy w zespole odtworzy jedną komendą.
Wdrożenie Astro na Cloudflare Workers przez Wrangler
Wdrożenie robisz przez Wrangler:
Albo połączenie w jednej komendzie w package.json:
Wrangler wysyła build (statyczne zasoby oraz Worker) na Cloudflare. Pierwsze wdrożenie tworzy Worker pod adresem {name}.{twoja-subdomena}.workers.dev, a potem dodajesz własną domenę w panelu Cloudflare.
W CI/CD najprostszy wariant to osobne zadanie GitHub Actions z oficjalną akcją Cloudflare:
Do środowiska testowego dodajesz osobną gałąź albo ręczne uruchamianie procesu CI/CD i zmieniasz komendę na deploy --env staging. Pamietaj, że jeśli prerender używa zmiennych środowiskowych, build dla środowiska testowego i produkcji powinien być wykonany osobno.
Środowiska w Astro i Cloudflare Workers: podgląd, testy i produkcja
Od Astro 6 sposób obsługi środowisk stał się znacznie bardziej rygorystyczny. W Astro 5 budowałeś raz i deployowałeś z flagą --env, a teraz build musi być oddzielny dla każdego środowiska, bo pre-rendering używa innych wartości zmiennych.
W wrangler.jsonc:
Dla większości projektów rekomenduję osobny proces CI/CD dla każdego środowiska. GitHub Actions z osobnym zadaniem dla środowiska testowego i produkcji, uruchamianym z innej gałęzi.
Remote bindings w Astro: zdalne zasoby w lokalnym środowisku
Domyślnie lokalne środowisko korzysta z lokalnych wersji zasobów. To bezpieczne, ponieważ testujesz kod bez ryzyka przypadkowego zapisu do produkcyjnej bazy D1 albo bucketu R2. Problemy zaczynają się wtedy, gdy lokalna baza nie ma prawdziych danych i cały scenariusz testowy robi się sztuczny, przez co mający słabsze odniesienie do rzeczywistości.
Do takich przypadków służą zdalne bindings (remote bindings). W konfiguracji oznaczasz konkretny binding jako zdalny:
Mechanizm nie należy do skomplikowanych, ponieważ twój kod nadal uruchamia się lokalnie w workerd, ale zapytania do wskazanego zasobu są przekazywane do realnego zasobu na koncie Cloudflare. Jest do dobre rozwiązanie do testów integracyjnych na danych ze środowiska testowego, weryfikacji migracji i debugowania problemów, których lokalna symulacja nie odtwarza.
Warto też pamiętać o kosztach i opóźnieniach: lokalny kod jest szybki, ale każde odwołanie do zdalnego zasobu przechodzi przez sieć i może naliczać operacje tak jak normalne użycie usługi Cloudflare.
Astro na Cloudflare Workers: wynik statyczny czy serwerowy
Najczęstszy błąd przy wdrożeniach Astro na Cloudflare to dodanie adaptera bez decyzji, czy projekt naprawdę potrzebuje środowiska wykonawczego Workera.
| Tryb | Kiedy używać | Konsekwencja |
|---|---|---|
output: 'static' | Blog, dokumentacja, landing, portfolio bez dynamicznych endpointów | Brak adaptera i brak bindings; wynik można serwować z dowolnego CDN |
output: 'static' + prerender = false | Większość stron statyczna, pojedyncze endpointy lub Server Islands | Adapter potrzebny tylko dla tras renderowanych na żądanie |
output: 'server' | Cały projekt zależy od cookies, sesji, D1/KV/R2 albo dynamicznych danych | Każda trasa przechodzi przez środowisko wykonawcze Workera |
Optymalizacja obrazów w Astro na Cloudflare
Aktualny adapter Cloudflare może używać Cloudflare Images binding do optymalizacji obrazów. Zamiast optymalizacji podczas budowania w Node (), obrazy są przekształcane na brzegu sieci w czasie żądania, jeśli używasz domyślnego imageService: 'cloudflare-binding'.
Efekt? Obraz automatycznie zmniejszany, kompresowany i serwowany przez najbliższy punkt Cloudflare. Żadnej pracy w czasie builda i żadnego konfigurowania .
Jeśli wolisz klasyczną optymalizację podczas budowania (np. masz już proces obróbki zdjęć w repozytorium), ustaw imageService: 'compile' w konfiguracji adaptera. Jeśli obrazy obsługuje zewnętrzny CDN albo CMS, możesz użyć imageService: 'passthrough'.
Debugowanie Cloudflare Workers na produkcji
Cloudflare Workers Dashboard daje Ci wgląd w logi, metryki i odsetek błędów. W codziennej pracy przydaje się też:
To przesyła logi w czasie rzeczywistym ze wszystkich instancji Workera. Przydatne szczególnie do debugowania problemów, które nie pojawiają się lokalnie.
Dla bardziej zaawansowanego monitoringu rozważ Cloudflare Workers Analytics Engine (do custom metrics) albo integrację z Sentry przez @sentry/cloudflare.
Zmienne środowiskowe i sekrety w Cloudflare Workers
Dwie kategorie:
Vars to jawne zmienne dostępne w kodzie i zapisywane w wrangler.jsonc:
Secrets są ustawiane przez Wrangler CLI, szyfrowane po stronie Cloudflare i nie trafiają do kodu:
Dla lokalnego środowiska tworzysz .dev.vars:
W kodzie dostęp przez env.DATABASE_URL po imporcie z cloudflare:workers.
Limity Cloudflare Workers dla projektów Astro
Workers nie są Node.js i ta różnica ma znaczenie przed zaprojektowaniem architektury. Limit czasu CPU w planie darmowym wynosi 10 ms na żądanie, a w planie płatnym domyślnie 30 s, z możliwością podniesienia do 5 minut. Czas CPU to nie całkowity czas odpowiedzi, więc fetch() do zewnętrznego API nie liczy się w ten sam sposób, ale ciężkie obliczenia, takie jak przetwarzanie dużych JSON-ów, kryptografia i manipulacja obrazami, mogą trafić w ścianę.
Rozmiar paczki nie może przekroczyć 3 MB po kompresji w planie darmowym i 10 MB w planie płatnym. Dla typowego projektu Astro to nie problem, ale uważaj na moment.js, lodash bez i pełne AWS SDK. Workers nie mają fs: statyczne zasoby są serwowane przez Assets binding, a nie przez czytanie plików w środowisku wykonawczym. Limit dodatkowych zapytań z jednego wywołania Workera wynosi 50 w planie darmowym i 10 000 w planie płatnym. Dla stron z wieloma wywołaniami API weryfikuj ten limit przed wdrożeniem, nie po.
Cloudflare Workers czy Vercel: kiedy wybrać które wdrożenie
W 2026 roku to realny podział rynku. Dane z projektów wskazują jasno:
Cloudflare + Astro wygrywa przy globalnym ruchu, niskim budżecie i usługach przechowywania danych blisko kodu: KV, R2, D1. Vercel zostaje lepszym wyborem przy Next.js, React Server Components, PPR i zespole, który ma już dobrze ułożony proces pracy. Nie przenosiłbym takiego projektu na siłę.
Dla stron Astro domyślny wybór to Cloudflare, a dla aplikacji Next.js będzie to Vercel. Szersze porównanie frameworków opisałem w osobnym artykule.


