Szybka odpowiedź: jak uruchamiać zadania cron w Next.js?
- Next.js nie ma harmonogramu, więc zadanie umieszczasz w Route Handlerze wywoływanym z zewnątrz.
- Vercel Cron pasuje do prostych zadań z
vercel.json, a Upstash QStash do opóźnionych i z ponawianiem. - Cron w GitHub Actions sprawdzi się przy rzadkich automatyzacjach repozytorium.
- Zawsze zabezpieczaj adres zadania, np.
CRON_SECRETalbo podpisem QStash. - Projektuj zadania jako idempotentne, bo harmonogram może pominąć albo powtórzyć termin.
Problem: Next.js nie ma wbudowanego crona
Z tej luki wychodzi się na trzy sposoby, każdy do innej skali problemu: Vercel Cron Jobs, Upstash QStash i GitHub Actions cron. Po kolei.
Vercel Cron Jobs w Next.js
Vercel pozwala definiować w vercel.json.
Takie zadania wywołują Route Handlery o określonych porach.
Vercel oznacza obecnie klasyczne Cron Jobs jako legacy i wskazuje Schedules, które obsługuje m.in. strefy czasowe i tworzenie harmonogramów w runtime. Poniższa konfiguracja i limity dotyczą klasycznego mechanizmu crons. Cały przykład wymaga Pro lub Enterprise: wpis co sześć godzin nie przejdzie wdrożenia na Hobby, gdzie pojedynczy cron może działać najwyżej raz dziennie.
Składnia cron: minute hour day-of-month month day-of-week
0 8 * * *: codziennie o 8:00 UTC0 3 * * 0: co niedzielę o 3:00 UTC0 */6 * * *: co 6 godzin*/15 * * * *: co 15 minut
Vercel interpretuje harmonogram w UTC i wywołuje metodą GET wyłącznie aktualne wdrożenie produkcyjne. Nie używaj lokalnej godziny bez przeliczenia zmian czasu letniego. Cron nie podąża też za odpowiedziami 3xx, więc path musi prowadzić bezpośrednio do istniejącego handlera, bez przekierowania.
Route Handler jako adres zadania cron
Przykład raportuje poprzednią dobę UTC, niezależnie od strefy harmonogramu. Nie nadrabia pominiętych dni: kolejne uruchomienie wylicza nową datę. Jeśli raporty muszą być kompletne, zapisuj przetworzone okresy i uzupełniaj brakujące; dla polskiej doby biznesowej oblicz granice w Europe/Warsaw, a następnie przelicz je na UTC.
Resend przechowuje klucz idempotencji przez 24 godziny i wymaga identycznego payloadu przy ponowieniu. Zmienione statystyki pod tym samym kluczem mogą dać 409 invalid_idempotent_request, a późne ponowienie po wygaśnięciu klucza może ponownie wysłać mail. Dla trwałej ochrony zapisuj niezmienny raport i stan wysyłki w bazie; samo ponowne obliczenie statystyk nie zapewnia stabilnego payloadu.
Zabezpieczenie zadania cron przez CRON_SECRET
W panelu Vercel przejdź do zakładki Settings, a następnie Environment Variables i dodaj zmienną CRON_SECRET. Vercel będzie automatycznie przekazywał jej wartość w nagłówku Authorization przy każdym wywołaniu zadania cron.
maxDuration jest wskazówką dla platformy wdrożeniowej, a nie sposobem na nieograniczone wykonanie. Rzeczywisty limit zależy od hostingu i planu. Vercel nie ponawia nieudanych zadań cron, może jednak uruchomić ten sam termin więcej niż raz i rozpocząć kolejne wykonanie, zanim poprzednie zdąży się zakończyć. Klucz idempotencji u dostawcy poczty elektronicznej zabezpiecza wyłącznie tę pojedynczą operację, dlatego zmiany w bazie danych należy chronić transakcjami oraz unikalnymi kluczami biznesowymi. Dodatkowo, przed równoległym uruchomieniem zadań warto zastosować blokadę rozproszoną z czasem wygaśnięcia TTL.
Upstash QStash jako bezserwerowa kolejka wiadomości
to kolejka wiadomości z HTTP API. Sprawdza się przy zadaniach, które mają być dostarczone co najmniej raz ( ), mogą być opóźnione albo wymagają automatycznego ponawiania. „Co najmniej raz” oznacza, że odbiorca musi tolerować duplikaty. Nie oznacza to nieskończonej liczby prób ani gwarancji sukcesu operacji biznesowej: po wyczerpaniu retry potrzebna jest obsługa niepowodzenia przez callback lub DLQ.
Zaplanowanie zadania w Upstash QStash
enqueueWeeklyReport() zleca pojedyncze wykonanie, a nie cotygodniowy harmonogram — do cykliczności służy schedules.create. Losowy jobId identyfikuje publikację i jej ponowienia; dwa wywołania akcji tworzą dwa różne zadania. Jeśli raport ma być wysłany raz na tydzień, użyj trwałego klucza biznesowego uwzględniającego okres, odbiorcę i ewentualnie tenant oraz przypisz mu niezmienny payload.
Zmienne QSTASH_TOKEN oraz APP_URL są wykorzystywane wyłącznie po stronie serwera, dlatego nie wymagają publicznego prefiksu. Warto też pamiętać, że Server Action nie stanowi pełnej granicy zaufania, ponieważ przed uruchomieniem kosztownego zadania należy każdorazowo zweryfikować sesję użytkownika, jego rolę oraz poprawność danych wejściowych. Ponadto parametr retries: 3 oznacza dokładnie trzy dodatkowe ponowienia po pierwszej próbie, co daje łącznie maksymalnie cztery próby dostarczenia zadania.
Odbiór zadania QStash w Route Handler
Wrapper wymaga QSTASH_CURRENT_SIGNING_KEY i QSTASH_NEXT_SIGNING_KEY do weryfikacji rotowanych podpisów. Osobny QSTASH_TOKEN jest potrzebny klientowi publikującemu, nie samemu odbiorcy. Weryfikacja podpisu potwierdza nadawcę, ale nie zapobiega ponownemu dostarczeniu poprawnie podpisanej wiadomości. jobId musi więc trafić do trwałego klucza idempotencji, unikalnego indeksu albo transakcji. Funkcja sendReportEmail z przykładu powinna przekazać ten klucz do dostawcy wiadomości. W produkcji generateWeeklyReport() powinno odtwarzać zapisany raport przypisany do zadania, zamiast zmieniać okres lub treść przy każdym retry. Pamiętaj o ograniczonym oknie idempotencji dostawcy opisanym przy Resend.
Typowe zastosowania QStash w Next.js
QStash schedules mają maksymalną rozdzielczość jednej minuty; dostarczenie pojedynczej wiadomości możesz natomiast opóźnić o sekundy. Jawny scheduleId pozwala aktualizować istniejący harmonogram zamiast przypadkowo tworzyć kolejny przy każdym wdrożeniu. Po wyczerpaniu ponowień obsłuż failureCallback albo kontroluj kolejkę niedostarczonych zadań (Dead Letter Queue). Adres failureCallback jest również publiczny, dlatego zabezpiecz go przez verifySignatureAppRouter, tak jak adres odbierający zadanie.
GitHub Actions cron jako alternatywa
Dla prostych zadań GitHub Actions może uruchamiać workflow według harmonogramu:
Najkrótszy obsługiwany interwał wynosi 5 minut, ale GitHub nie daje nam jakichkolwiek gwarancji punktualnego startu. Przy dużym obciążeniu workflow może się opóźnić, a oczekujące uruchomienie nawet wypaść (szczególnie obciążony bywa początek godziny). Harmonogram działa tylko z domyślnej gałęzi, a w publicznym repozytorium zostaje automatycznie wyłączony po 60 dniach bez aktywności. Koszt zależy od widoczności repozytorium, użytego runnera i planu GitHub, więc nie zakładaj stałego limitu 2000 darmowych minut.
Czy cron powinien działać na Edge Runtime?
Edge Runtime nie jest harmonogramem, ale środowiskiem wykonania, więc nadal potrzebujesz Vercel Cron, QStash, GitHub Actions albo systemowego crona, który wywoła adres zadania. W Next.js domyślnym i rekomendowanym środowiskiem wykonania Route Handlera jest Node.js. Wybór export const runtime = 'edge' ma sens tylko wtedy, gdy wszystkie zależności zadania, w tym klient bazy i SDK dostawców, obsługują Edge. Nie omija też limitów czasu platformy.
after() z Next.js również nie zastępuje crona. Pozwala kontynuować pracę po wysłaniu odpowiedzi, ale callback nadal działa w ramach maxDuration tego samego wywołania i sam nie uruchomi się o wybranej godzinie. Podobnie setInterval lub timer utworzony przy starcie modułu jest niewiarygodny w środowisku bezserwerowym: instancja może zostać zamrożona albo usunięta w dowolnym momencie.
Idempotencja, blokady i monitoring zadań cron
Nie projektuj zadania na założeniu dokładnie jednego wykonania. Vercel może zarówno pominąć, jak i powtórzyć termin. QStash wykonuje skonfigurowaną liczbę ponowień, więc ta sama wiadomość może dotrzeć więcej niż raz. GitHub Actions może wystartować później lub pominąć oczekujące wykonanie przy dużym obciążeniu.
Idempotencję buduj na stabilnym kluczu biznesowym, np. daily-report/2026-07-16 albo ID konkretnego zdarzenia. Zapisuj go w bazie z unikalnym indeksem i używaj transakcji tam, gdzie skutek dotyczy danych. Dla zewnętrznych efektów ubocznych korzystaj z kluczy idempotencji dostawcy. Deduplication QStash ogranicza ponowne opublikowanie wiadomości w dziesięciominutowym oknie, ale nie zwalnia odbiorcy z obsługi powtórnego dostarczenia.
Jeżeli dwa wykonania nie mogą działać równolegle, zastosuj blokadę we współdzielonym magazynie z unikalnym tokenem właściciela i TTL. Czas dłuższy od typowego wykonania nie daje gwarancji: po wygaśnięciu blokady inny worker może ją przejąć, choć pierwszy nadal pracuje. Odnawiaj dzierżawę lub ogranicz czas pracy i obsługuj utratę blokady; przy ścisłej wyłączności zapis musi odrzucać operacje poprzedniego właściciela (np. przez fencing token). Zwolnienie w finally musi atomowo sprawdzać token właściciela, aby nie usunąć cudzej blokady. TTL pozostaje potrzebny, bo proces może zostać przerwany. Dla dużej liczby elementów zapisuj punkt kontrolny i przetwarzaj małe porcje, aby następne wykonanie mogło bezpiecznie wznowić pracę.
Monitoruj początek, koniec, czas trwania, liczbę przetworzonych rekordów, identyfikator uruchomienia i wynik. Zwracaj 2xx dopiero po rzeczywistym sukcesie; błąd przejściowy powinien dać 5xx, aby QStash wykonał ponowienie. Oprócz logów ustaw zewnętrzny sygnał kontrolny z maksymalnym dopuszczalnym opóźnieniem oraz alert na brak wykonania, bo brak żądania nie wygeneruje wyjątku w aplikacji.
Vercel Cron vs Upstash QStash vs GitHub Actions
| Metoda | Minimalny harmonogram | Ponowienia | Sposób rozliczania | Najlepsze zastosowanie |
|---|---|---|---|---|
| Vercel Cron | Hobby: dobowy; Pro: minuta | Brak automatycznych | Zużycie Vercel Functions | Proste zadania cykliczne |
| Upstash QStash | Minuta; opóźnienie od sekund | Automatyczne, konfigurowalne | Wiadomości i wywołania | Ponowienia, kolejki i opóźnienia |
| GitHub Actions | 5 minut | Logika workflow lub ręczny rerun | Minuty runnera według planu | Rzadkie zadania repozytorium |
| Cron hostowany samodzielnie | Zwykle 1 minuta | Własna implementacja | Serwer i utrzymanie | Pełna kontrola |


