Zmienne środowiskowe i sekrety#

Sekrety nie należą do repozytorium#

Klucze API, connection stringi i tokeny nigdy nie trafiają do Gita. Vercel przechowuje je jako Environment Variables — szyfrowane, wstrzykiwane do buildu i runtime, niewidoczne w kodzie. To podstawa higieny bezpieczeństwa.

Trzy środowiska#

Vercel rozdziela zmienne na trzy konteksty. Tę samą nazwę możesz przypisać do każdego z inną wartością:

Środowisko	Kiedy używane
Production	Deploy z main
Preview	PR-y i gałęzie inne niż main
Development	Lokalne vercel dev

DATABASE_URL (Production) = postgres://prod...
DATABASE_URL (Preview)    = postgres://staging...

Publiczne vs poufne — kluczowa różnica#

W Next.js prefiks NEXT_PUBLIC_ jest wbudowywany do bundla przeglądarki. Wszystko z tym prefiksem widzi każdy użytkownik w kodzie strony.

• NEXT_PUBLIC_API_URL — OK, to publiczny adres.
• DATABASE_URL, STRIPE_SECRET_KEY — bez prefiksu, tylko po stronie serwera (API routes, Server Components).

Wskazówka: Złota zasada — żaden sekret nie może mieć prefiksu NEXT_PUBLIC_. Jeśli wartość jest poufna, musi być dostępna wyłącznie na serwerze. Pomyłka tutaj to wyciek klucza do każdego odwiedzającego.

Dodawanie zmiennych#

Przez panel#

Projekt → Settings → Environment Variables. Wpisujesz nazwę, wartość, zaznaczasz środowiska. Po dodaniu konieczny jest redeploy, by zmiana weszła do buildu.

Przez CLI#

# Dodaj zmienną dla produkcji
vercel env add STRIPE_SECRET_KEY production

# Pobierz wszystkie zmienne do lokalnego .env.local
vercel env pull .env.local

# Lista zmiennych
vercel env ls

Lokalny rozwój#

Trzymaj lokalne sekrety w .env.local i dopisz go do .gitignore:

# .gitignore
.env.local
.env*.local

vercel env pull pobierze wartości z platformy, więc cały zespół pracuje na spójnym zestawie bez przekazywania sekretów przez czaty.

Dobre praktyki ProfessNet#

1. Sekrety tylko w Vercelu, nigdy w repo — nawet w komentarzu.
2. Osobne wartości dla Production i Preview (preview nie rusza prod-DB).
3. Rotuj klucze po odejściu osoby z dostępem do Teamu.
4. Po zmianie zmiennej zrób redeploy — stary build trzyma starą wartość.
5. Minimalizuj NEXT_PUBLIC_ do absolutnie publicznych danych.

Podsumowanie#

Vercel daje szyfrowany magazyn zmiennych z podziałem na trzy środowiska. Pamiętaj o granicy: NEXT_PUBLIC_ = widoczne dla wszystkich, reszta = tylko serwer. Zarządzaj sekretami przez panel lub CLI, trzymaj .env.local poza Gitem, a po każdej zmianie wymuszaj redeploy.