Kategoria: Next.js, React i TypeScript

Next.js: process.env działa na serwerze, ale undefined w przeglądarce

Poradnik techniczny · Kacper Bernecki

Zmienna API istnieje podczas renderowania serwera, a w Client Component odczyt daje undefined. Next.js nie udostępnia zwykłych server-only variables do kodu przeglądarki; publiczne muszą być jawnie oznaczone.

Jak ustalić źródło błędu

Sprawdź, czy odczyt odbywa się w pliku z dyrektywą use client i czy nazwa zaczyna się od NEXT_PUBLIC_.

Zweryfikuj docelowe środowisko build oraz to, czy nowa wartość została uwzględniona w nowym deploymencie.

Co zrobić krok po kroku

1. Nie przenoś sekretnego klucza do klienta; jeśli trzeba, odczytaj go w Route Handler i zwróć wyłącznie potrzebny wynik.

2. Dla jawnej konfiguracji interfejsu ustaw NEXT_PUBLIC_ przed buildem i przebuduj aplikację.

Jak sprawdzić wynik

Publiczna wartość jest dostępna w nowym bundle, a tajny klucz nie występuje w kodzie JavaScript pobieranym przez przeglądarkę.

Czego nie robić

Nie dodawaj prefiksu NEXT_PUBLIC_ do kluczy prywatnych; oznacza to ich ujawnienie.