Next.js: Server Action przestaje działać po wdrożeniu — diagnostyka i naprawa
Poradnik techniczny · Kacper Bernecki
Problem: Server Action (funkcja server-side eksportowana jako action) działa w trybie deweloperskim, ale po wdrożeniu aplikacji nie wywołuje się, zwraca 4xx/5xx, lub klient otrzymuje błąd CORS/403/Invalid Server Actions request origin. Przyczyny są zwykle związane z konfiguracją routingu, build-time tree-shaking, zmianą domeny/origin, proxy i ustawieniami platformy (runtime, edge vs node), a nie z samą logiką biznesową. Dokument ten prowadzi konkretną diagnostykę różnicową, wymusza sprawdzenia plików routingu, nagłówków i metadanych żądań, proponuje test naprawy i zmiany konfiguracji, wskazując, które pliki i warunki trzeba zweryfikować po wdrożeniu, bez przyjmowania, że lokalny dev mirror automatycznie odpowiada produkcji.
Jak rozpoznać przyczynę
Sprawdź, czy Server Action jest faktycznie eksportowana z pliku Server Component lub z /app route, a nie z Client Component. W produkcji tree-shaking lub build-time optymalizacje mogą usunąć nieużywane eksporty. Potwierdź, że plik ma pozycję w drzewie routingu i że żądanie trafia do tej ścieżki (np. POST do /api lub fetch z action).
Zbadaj nagłówki żądań po wdrożeniu: Origin, Referer, X-Requested-With, cookies i content-type. Błędy typu "Invalid Server Actions request origin mismatch" wynikają z różnic między build-time origin a rzeczywistym. Jeżeli aplikacja jest za proxy lub CDN, sprawdź czy nagłówki proxy (X-Forwarded-Host, X-Forwarded-Proto) są poprawnie ustawione i nie modyfikują origin.
Zwróć uwagę na runtime i target platformy: server actions mogą wymagać Node.js runtime, a wdrożenie na Edge Functions zmienia zachowanie (brak pewnych Node API, inny timeout). Sprawdź ustawienia platformy (np. Vercel: runtime: nodejs lub edge) oraz czy plik action nie odwołuje się do API niedostępnego na edge.
Rozwiązanie krok po kroku
1. Przeprowadź test „direct call”: wyślij żądanie POST bezpośrednio do endpointu Server Action z narzędzia curl z pełnymi nagłówkami Origin i Content-Type; porównaj odpowiedź lokalnie i z produkcji. Zanotuj różnice w statusie odpowiedzi i headerach.
2. Włącz szczegółowe logowanie błędów w buildzie produkcyjnym (jeśli platforma pozwala) albo zweryfikuj logi serwera/edge po wdrożeniu. Szukaj wpisów o odrzuceniu żądania z powodu origin mismatch, brakującego body parsera lub nieznanego eksportu.
3. Sprawdź pliki routingu i eksportów: otwórz plik z action i potwierdź, że jest eksportowany jako named export "export async function action(...)" lub używany przez Server Component. Upewnij się, że nie jest importowany tylko w Client Component, co uniemożliwi jego użycie jako Server Action.
4. Zbadaj konfigurację platformy: na Vercel sprawdź ustawienia funkcji serverless/edge w pliku vercel.json lub w dashboardzie; jeśli używasz innego hosta, potwierdź, że backend używa kompatybilnego runtime (Node.js) i że plik .vercelignore nie usuwa istotnych plików.
5. Przetestuj origin i proxy: wykonaj żądanie z produkcyjnego hosta do siebie (server-to-server) oraz z przeglądarki; porównaj nagłówki X-Forwarded-* i Origin. Jeśli origin jest zmieniony przez CDN, skonfiguruj forwarding właściwych nagłówków albo ustaw trusted proxies na serwerze.
6. Jeśli używasz ograniczeń CORS lub CSRF, zweryfikuj tokeny i nagłówki na produkcji. Upewnij się, że same action nie polegają na client-side cookies, których nie przesyłasz z produkcyjnym domen; sprawdź flagi Secure/SameSite dla ciastek.
7. Wykonaj izolowany build minimalnego repo: stwórz prosty Server Action, wdroż go jako oddzielny projekt na tej samej platformie; jeśli działa, porównaj różnice w zależnościach, webpack/next.config.js oraz env vars, które mogą wpływać na zachowanie.
Jak sprawdzić, czy problem zniknął
Test A: curl POST z produkcyjnego hosta z nagłówkiem Origin równym docelowej domenie; sprawdź kod HTTP 200 i oczekiwaną treść. Jeżeli zwraca 4xx, porównaj dokładnie odpowiedź z logów serwera.
Test B: Wdrożony minimalny Server Action (tylko zwraca JSON) na tej samej platformie. Jeśli minimalny przykład działa, problem leży w konfiguracji głównej aplikacji (proxy, env, build). Jeśli nie działa, problem platformowy lub globalny runtime.
Czego nie robić
Nie zakładaj, że lokalny dev odzwierciedla produkcję: różnice w origin, proxy, runtime (edge vs node) i env vars często powodują błędy; zawsze testuj bezpośrednio na wdrożeniu.
Unikaj usuwania logów produkcyjnych przed analizą: bez logów nie stwierdzisz, czy request dotarł, czy został odrzucony przez proxy/CDN, czy błędy pochodzą z action.