Vercel: zmienna środowiskowa ustawiona w panelu, ale nie działa w aplikacji
Poradnik techniczny · Kacper Bernecki
Problem: w panelu Vercel widzisz ustawioną zmienną środowiskową (Environment Variable), ale aplikacja zwraca brak wartości lub starą wartość, albo różnice między buildem a runtime. Przyczyny bywają techniczne i proceduralne: różne zakresy (Environment, Preview, Production), brak rebuildu po zmianie, użycie niewłaściwego mechanizmu odczytu (np. process.env w kliencie bez prefiksu NEXT_PUBLIC_), lokalne cache lub build cache Vercel, a także literówki w nazwie zmiennej. Zdiagnozowanie wymaga oddzielnego sprawdzenia fazy buildu i fazy runtime oraz potwierdzenia, że zmienna jest dostępna w tej fazie i dla tego projektu/gałęzi. Wersje frameworków (Next.js) i konfiguracje build-step też wpływają: Next.js wstawia wartości podczas buildu do kodu statycznego — zmiana zmiennej po buildzie nie zmieni już wygenerowanych plików statycznych bez ponownego deploya. Z tego powodu proponuję podejście systematyczne: (1) sprawdź scope zmiennej w panelu Vercel (Environment: Production/Preview/Development), (2) upewnij się, że wykonałeś deploy po każdej zmianie wartości, (3) zweryfikuj, czy używasz poprawnej konwencji (np. NEXT_PUBLIC_ dla wartości dostępnych w przeglądarce), (4) oceń, czy problem występuje podczas buildu czy runtime — logi builda i zmienne w logach serwera pomogą. Dalsze kroki obejmują odbudowę projektu z czyszczeniem cache, test z prostym-endpointem, który zwraca wartość process.env, oraz lokalne odtwarzanie ustawień przez vercel dev lub przez eksport zmiennych do środowiska uruchomieniowego. W poniższej diagnostyce podałem warianty przyczyn, konkretne kroki do wykonania i krótkie testy weryfikujące, które warunki eliminują potencjalne źródło błędu.
Jak rozpoznać przyczynę
Sprawdź zakres zmiennej w Panelu Vercel: każda zmienna ma Environment (Development, Preview, Production). Jeśli deployujesz na produkcji, ale zmienna ustawiona jest tylko dla Preview, aplikacja jej nie zobaczy. W panelu Projects → Settings → Environment Variables sprawdź, czy wpis znajduje się w oczekiwanym scope i dla właściwego projektu.
Rozróżnij build vs runtime: frameworki (np. Next.js) osadzają process.env w czasie buildu dla kodu client-side. Jeśli zmienna zmieniła się po ostatnim buildzie, należy wymusić nowy deploy. Dodatkowo cache builda może trzymać starą wartość — użyj opcji redeploy/purge cache.
Sprawdź nazewnictwo i dostępność client-side: zmienne używane w przeglądarce muszą mieć prefiks zgodny z frameworkiem (w Next.js NEXT_PUBLIC_). Zdarza się też literówka lub niewłaściwe odczytanie (np. użycie import.meta.env w projekcie, który nie wspiera tego).
Rozwiązanie krok po kroku
1. Zweryfikuj w Panelu Vercel: Projects → Settings → Environment Variables — potwierdź nazwę (case-sensitive), wartość oraz Environment (Production/Preview/Development). Zrób zrzut nazwy i porównaj dokładnie z tym, czego oczekuje kod.
2. Wykonaj ręczny redeploy (Deployments → Redeploy) dla środowiska, gdzie problem występuje, wybierając opcję 'Redeploy with Clear Cache' jeśli dostępna. Czekaj aż pojawią się pełne logi builda i przeanalizuj je pod kątem wypisanych wartości lub komunikatów o brakujących zmiennych.
3. Dodaj tymczasowy endpoint lub pole testowe w aplikacji serwerowej, które zwróci raw process.env['NAZWA_ZMIENNEJ'] podczas runtime. Upewnij się, że endpoint działa w tym samym environment co problem i nie wysyła wartości do klienta, jeśli to tajne.
4. Jeśli używasz frameworku typu Next.js i potrzebujesz zmiennej po stronie klienta, upewnij się, że nazwa zaczyna się od NEXT_PUBLIC_. Zmiana nazwy wymaga rebuild i redeploy; nie wystarczy tylko edycja kodu klienta.
5. Uruchom lokalnie vercel dev z tymi samymi zmiennymi (export NAZWA=wartosc lub użyj .env lokalnego) i potwierdź, czy problem jest reprodukowalny lokalnie. Jeśli lokalnie działa, porównaj logi builda i wersję Node/Builder używaną przez Vercel.
6. Sprawdź pliki build-step i konfiguracje w vercel.json (jeśli występuje) — niektóre custom buildery mogą izolować środowisko i nie przekazywać zmiennych do procesu builda. Usuń niestandardowe cache lub dodaj jawne env do build command jeśli potrzeba.
7. Jeżeli wszystko zawodzi, skopiuj nazwę zmiennej do prostego skryptu 'console.log(process.env.NAZWA)' uruchomionego jako serverless function w Vercel i sprawdź logi funkcji — to oddziela problem aplikacji od platformy.
Jak sprawdzić, czy problem zniknął
Test 1 — log builda: po redeploy sprawdź w zakładce Deployments pełny log builda. Powinien zawierać brak błędów typu 'undefined variable' i, jeśli w kodzie umieścisz tymczasowy console.log(process.env.NAZWA), będzie widoczny w logach builda.
Test 2 — runtime function: wdroż prostą serverless function (api/test.js) zwracającą process.env.NAZWA. Wywołaj endpoint po deployu i porównaj zwróconą wartość z tą w panelu; różnica wskaże problem fazy runtime vs build.
Test 3 — klient vs server: w aplikacji client-side wypisz valor NEXT_PUBLIC_NAZWA do konsoli przeglądarki po załadowaniu strony. Jeśli undefined, sprawdź czy zmienna ma prefiks i czy deploy był rebuildem — to odróżni problem exposingu od scope.
Czego nie robić
Nie robienie redeploy po zmianie wartości: zmienne osadzone w buildzie wymagają pełnego rebuild; jedynie edytowanie wartości w panelu bez redeploy nie zaktualizuje statycznych artefaktów.
Używanie zmiennych tajnych po stronie klienta bez prefiksu: ujawnianie sekretów do frontendu to błąd; brak prefiksu powoduje też, że framework nie udostępnia zmiennej dla client-side.
Zakres ustawiony w niewłaściwym environment: ustawienie zmiennej tylko dla Preview nie wystarczy dla Production — sprawdź scope zgodny z aktywnym deployem.