Zmienne środowiskowe w CI
Przechowa Pan/Pani sekrety w GitHub Secrets, wstrzyknie je do procesu budowania jako zmienne środowiskowe i uzyska do nich dostęp w Vite przez import.meta.env lub w Next.js przez process.env.
Zmienne środowiskowe w CI to bezpłatna lekcja Frontend Academy na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Frontend Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Frontend Academy zawiera 4 lekcji w sumie.
Dlaczego różne środowiska?
Aplikacje potrzebują różnych wartości w zależności od środowiska: adresu API dla środowiska deweloperskiego, adresu API dla środowiska stagingowego i adresu API dla środowiska produkcyjnego. Potrzebują także sekretów (kluczy API i tokenów), które nigdy nie mogą trafić do repozytorium. Zmienne środowiskowe to standardowy sposób dostarczania tych wartości.
Publiczne a tylko serwerowe
Zmienne frontendu osadzone w bundlu są publiczne — każdy może je zobaczyć za pomocą narzędzi deweloperskich przeglądarki. Nigdy nie należy umieszczać tam sekretów. Zmienne serwerowe, używane w funkcjach serverless, SSR i trasach API, mogą być prawdziwymi sekretami.
Zmienne środowiskowe Vite
Vite udostępnia kodowi klienta zmienne z prefiksem VITE_ za pośrednictwem import.meta.env.
# .env
VITE_API_URL=https://api.example.com
VITE_FEATURE_FLAGS={"newOnboarding":true}
# In code:
const apiUrl = import.meta.env.VITE_API_URL;
# DEV_ONLY or NEVER PREFIXED vars are NOT exposed:
SECRET_KEY=xxx # not accessible to client codeZmienne środowiskowe Next.js
Next dodaje prefiks NEXT_PUBLIC_ do zmiennych publicznych. Zmienne przeznaczone wyłącznie dla serwera nie mają prefiksu (są używane w Route Handlers i getServerSideProps).
# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com # client-accessible
DATABASE_URL=postgres://... # server-only
# Client:
const url = process.env.NEXT_PUBLIC_API_URL;
# Server (API route):
const db = process.env.DATABASE_URL;Lokalne pliki .env
Pliku .env.local należy używać do osobistych nadpisań, a plików .env.development i .env.production do wartości domyślnych właściwych dla danego środowiska. Plik .env.local należy dodać do .gitignore — sekretów nigdy nie należy zatwierdzać w repozytorium.
# .gitignore
.env.local
.env.*.local
# Commit only .env.example with placeholder values:
VITE_API_URL=https://api.example.com
DATABASE_URL=Przechowywanie sekretów w GitHub Actions
Sekrety należy dodać w repozytorium w sekcji Ustawienia → Sekrety i zmienne → Actions. Dostęp do nich uzyskuje się przez secrets.NAME.
# .github/workflows/deploy.yml
- name: Deploy
env:
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
run: |
npx vercel --token $VERCEL_TOKEN --prod
npx sentry-cli releases new $RELEASESekrety właściwe dla środowiska
Środowiska GitHub (Ustawienia → Środowiska) umożliwiają przypisanie sekretów do konkretnego środowiska (staging lub production) oraz opcjonalne skonfigurowanie etapów wymagających zatwierdzenia.
# Job that requires environment:
deploy-prod:
environment: production # requires reviewer approval if configured
steps:
- run: deploy
env:
DB_URL: ${{ secrets.DB_URL }} # only prod's DB_URL is exposedZmienne środowiskowe dostawcy hostingu
Vercel, Netlify i Cloudflare udostępniają zmienne środowiskowe podczas kompilacji oraz w czasie działania aplikacji. Można je ustawić w panelu lub za pomocą CLI.
# Vercel:
vercel env add VITE_API_URL production
vercel env add VITE_API_URL preview
# Netlify:
netlify env:set VITE_API_URL https://api.example.com
# Cloudflare Pages:
wrangler pages secret put API_URLNie wpisuj sekretów na stałe do bundli frontendu
Jeśli wartość znajduje się w kodzie JavaScript klienta, jest publiczna. Klucze API dla zewnętrznych SDK (klucz publikowalny Stripe, klucz wyszukiwania Algolia) są zaprojektowane jako publiczne. Wszystkie pozostałe klucze API serwera muszą pozostać po stronie backendu.
Sprawdzanie zmiennych środowiskowych podczas kompilacji
Należy użyć zod lub envalid, aby kompilacja kończyła się niepowodzeniem, jeśli brakuje wymaganych zmiennych środowiskowych.
// env.ts
import { z } from 'zod';
const envSchema = z.object({
VITE_API_URL: z.string().url(),
VITE_SENTRY_DSN: z.string().url().optional()
});
export const env = envSchema.parse(import.meta.env);
// Throws helpful error if VITE_API_URL is missingCzas kompilacji a czas działania
Zmienne środowiskowe czasu kompilacji są osadzane w bundlu — ich zmiana wymaga ponownej kompilacji. Zmienne środowiskowe czasu działania (trasy API Next, Netlify Functions, Cloudflare Workers) są odczytywane przy każdym żądaniu. Wyboru należy dokonać w zależności od tego, czy dana wartość powinna zmieniać się bez ponownego wdrażania aplikacji.
Rotacja sekretów
Sekrety należy regularnie rotować (co 90 dni) oraz po każdej zmianie w zespole. Narzędzia takie jak 1Password Secrets Automation i AWS Secrets Manager pomagają utrzymywać aktualne sekrety w CI bez ręcznych zmian.
Typowe pułapki
1) Zatwierdzanie pliku .env z prawdziwymi sekretami — należy użyć git-secrets, aby temu zapobiec. 2) Ujawnianie zmiennych serwerowych klientowi (niewłaściwy prefiks). 3) Zapominanie o ustawieniu zmiennych środowiskowych we wdrożeniach podglądowych. 4) Mieszanie kluczy testowych i produkcyjnych w tym samym środowisku.
Szybkie sprawdzenie
Dlaczego zmienne środowiskowe Vite udostępniane klientowi muszą mieć prefiks VITE_?
Podsumowanie: zmienne środowiskowe w CI
Zmienne publiczne: mają prefiks (VITE_, NEXT_PUBLIC_), są osadzane w bundlu i widoczne dla użytkowników. Zmienne przeznaczone wyłącznie dla serwera: nie mają prefiksu i są używane w trasach API oraz SSR. Plik .env.local należy umieścić w .gitignore, a plik .env.example zatwierdzić w repozytorium. Sekrety GitHub służą do konfiguracji CI, a środowiska GitHub do ograniczania dostępu w produkcji. Dostawcy hostingu (Vercel, Netlify, Cloudflare) ustawiają zmienne osobno dla każdego środowiska. Zmienne należy sprawdzać podczas kompilacji za pomocą zod.
Ucz się HTML dzięki korepetycjom AI — za darmo
Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.
- Kursy
- 41
- Lekcje
- 163
Często zadawane pytania
Czy lekcja „Zmienne środowiskowe w CI” jest bezpłatna?
Tak — pełny tekst „Zmienne środowiskowe w CI” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Frontend Academy, przejdź na CoddyKit PRO. Kurs Frontend Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Zmienne środowiskowe w CI”?
Przechowa Pan/Pani sekrety w GitHub Secrets, wstrzyknie je do procesu budowania jako zmienne środowiskowe i uzyska do nich dostęp w Vite przez import.meta.env lub w Next.js przez process.env. Ćwiczysz Frontend Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć Frontend Academy?
Nie wymagamy żadnego doświadczenia. Frontend Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.
Ile czasu zajmuje lekcja „Zmienne środowiskowe w CI”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji Frontend Academy?
Tak. Każda lekcja Frontend Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- GitHub Actions dla frontendu: lint, test i build
- Wdrażanie na Vercel, Netlify i Cloudflare Pages
- Zmienne środowiskowe w CI
- Automatyczne kontrole Lighthouse