Generator .env.example

Generator .env.example – szablon konfiguracji, który bezpiecznie trafia do repozytorium

Generator .env.example składa szablon zmiennych środowiskowych dla Laravela, Node.js i Pythona. Wybierz framework (albo jeden z czterech gotowych zestawów), wpisz nazwę aplikacji, wskaż bazę danych i zdecyduj, czy projekt używa Redisa, poczty i plików w S3. Wynik to plik z pełną listą kluczy pogrupowanych komentarzami sekcji, w którym każdy sekret ma pustą wartość, czyli dokładnie taki, jaki powinien trafić do Gita obok kodu. Masz już działający .env? Wklej go w dolnej części narzędzia, a dostaniesz .env.example z wyczyszczonymi hasłami i kluczami.

Po co .env.example, jeśli .env jest ignorowany

Plik .env z prawdziwym hasłem do bazy i kluczem aplikacji nie ma czego szukać w repozytorium, dlatego trafia do .gitignore. Razem z nim znika jednak jedyna lista mówiąca, jakich zmiennych aplikacja potrzebuje: nowa osoba klonuje projekt i dostaje wyjątek o kluczu, którego nazwy nie ma nigdzie w kodzie. .env.example zamyka tę lukę i jest wersjonowany, więc nowa integracja jest w diffie widoczna jako nowy klucz. Zakładając repozytorium, wygeneruj najpierw listę ignorowanych ścieżek w generatorze .gitignore i sprawdź, czy .env jest na niej, a .env.example nie.

Co generuje generator .env.example

Trzy szablony odpowiadają trzem konwencjom nazewniczym: Laravel trzyma parametry bazy w osobnych zmiennych, Node.js i Python w jednym adresie połączenia DATABASE_URL. Przełączniki Redisa, poczty i S3 dokładają własne bloki, a wynik przechodzi przez deduplikację kluczy. Domyślny zestaw Laravel + MySQL + Redis + poczta daje 26 zmiennych w 5 sekcjach, z czego 5 ma puste wartości do uzupełnienia.

Przy opcji „Brak / SQLite” Laravel dostaje DB_CONNECTION=sqlite i zakomentowaną ścieżkę do pliku bazy, a w Node.js i Pythonie DATABASE_URL zostaje zakomentowany. Pod wynikiem narzędzie pokazuje rozwijaną tabelę z opisem każdej zmiennej oraz kroki „Co dalej” z poleceniami dla wybranego frameworka.

Zmienna środowiskowa a plik .env

Zmienna środowiskowa jest własnością procesu: ustawia ją system, kontener albo panel hostingu i istnieje niezależnie od plików w katalogu. .env to tylko wygodny sposób załadowania zestawu takich zmiennych na maszynie deweloperskiej – czyta go biblioteka, nie system. Zmienna już obecna w środowisku najczęściej nie zostanie nadpisana wpisem z pliku, dlatego na produkcji .env zwykle nie jest potrzebny: konfigurację wstrzykuje menedżer sekretów albo dyrektywa serwera, na przykład SetEnv z generatora pliku .htaccess. .env.example zostaje kontraktem: mówi, co dostarczyć, nie skąd.

Wartości: puste sekrety, atrapy, cudzysłowy i spacje

Zasada jest jedna: żadna wartość w .env.example nie może być prawdziwa. Klucze podpisu, loginy i hasła zostają puste, żeby aplikacja zgłosiła błąd przy pierwszym uruchomieniu, zamiast po cichu wystartować na wartości z przykładu. Nieszkodliwe ustawienia, takie jak APP_ENV=local, PORT=3000 czy 127.0.0.1, warto wpisać, bo skracają start projektu do jednego cp .env.example .env. Adres bazy generator pokazuje w komentarzu (np. postgres://USER:PASSWORD@localhost:5432/DATABASE), a wartość DATABASE_URL zostawia pustą: w repozytorium nie leży wtedy ciąg wyglądający jak działający login z hasłem. Lokalny REDIS_URL bez hasła jest wpisany od razu.

Osobna pułapka to cytowanie. Wartość bez cudzysłowów kończy się na pierwszej spacji albo na znaku #, więc nazwa z dwóch słów wymaga cudzysłowów. W cudzysłowach podwójnych część bibliotek rozwija ${INNA_ZMIENNA} i sekwencje ucieczki, w apostrofach nie. Generator cytuje nazwę aplikacji tylko wtedy, gdy musi (spacja, polskie znaki), a znaki $, ` i \ z niej usuwa, żeby nie uruchomiły interpolacji:

APP_NAME=MyApp
APP_NAME="Acme Shop"
MAIL_FROM_NAME="${APP_NAME}"
DB_PASSWORD=

Prawdziwe sekrety tworzysz później i lokalnie. Kroki pod wynikiem podają gotowe polecenia: php artisan key:generate dla Laravela, openssl rand -hex 32 dla JWT_SECRET i python -c "import secrets; print(secrets.token_urlsafe(50))" dla SECRET_KEY.

Jak zamienić gotowy .env na .env.example

Wklej zawartość pliku w polu „Masz już plik .env?” i wybierz tryb. „Tylko wrażliwe wartości” czyści hasła, tokeny, klucze, loginy, adresy hostów i URL-e z danymi logowania, a zostawia porty, tryby, sterowniki, null/true/false, odwołania ${ZMIENNA} oraz lokalne hosty (localhost, 127.0.0.1). „Wszystkie wartości” zostawia same klucze i komentarze. Przykład w pierwszym trybie:

DB_HOST=127.0.0.1 zostaje bez zmian
DB_PORT=3306 zostaje bez zmian
DB_PASSWORD=tajne-haslo → DB_PASSWORD=
STRIPE_SECRET=sk_live_... → STRIPE_SECRET=

Konwersja działa w przeglądarce, treść pliku nie jest wysyłana na serwer. Limit to 200 000 znaków. Powtórzone klucze i linie niepasujące do formatu KLUCZ=wartość są pomijane (podsumowanie podaje ich liczbę), prefiks export zostaje. Wrażliwe wartości są rozpoznawane po nazwie klucza i wyglądzie wartości, więc przed commitem przejrzyj wynik: klucz o nietypowej nazwie i krótkiej wartości może przejść niezauważony.

Komentarze, kolejność kluczy i walidacja przy starcie

Wszystko od znaku # do końca linii jest komentarzem i to jedyne miejsce, w którym można wyjaśnić, skąd wziąć wartość i czy jest wymagana. Generator używa komentarzy jako nagłówków sekcji oraz jako zakomentowanych przykładów tam, gdzie wartość musi zostać pusta. Gdy oba pliki wymieniają klucze w tej samej kolejności, diff pokazuje braki w sekundę, dlatego nowe klucze dopisuj w tym samym miejscu w obu plikach.

Sam szablon nie zmusi nikogo do wypełnienia pól, dlatego obecność wymaganych zmiennych warto sprawdzać na starcie procesu, a nie w chwili, gdy jakaś funkcja pierwszy raz sięgnie po klucz API. Brak konfiguracji ma zatrzymać wdrożenie od razu, z komunikatem wskazującym nazwę zmiennej. W Laravelu naturalnym miejscem są pliki z katalogu config czytające zmienne przez env() (po php artisan config:cache wywołania env() poza tym katalogiem zwracają null), a w Django moduł ustawień z konfiguratora settings.py.

Jak korzystać z generatora

1. Wybierz framework albo kliknij gotowy zestaw, np. „Laravel + PostgreSQL + S3” lub „Node.js API + PostgreSQL”. Od frameworka zależą nazwy zmiennych i sposób opisu bazy.
2. Wpisz nazwę aplikacji (do 60 znaków); nazwa z kilku słów dostanie cudzysłowy automatycznie, a puste pole da MyApp.
3. Wskaż bazę: MySQL / MariaDB, PostgreSQL albo brak zewnętrznej bazy przy SQLite.
4. Zaznacz Redisa, pocztę i S3, jeśli projekt ich używa.
5. Kliknij „Generuj .env.example”, skopiuj albo pobierz wynik i zapisz go w katalogu głównym repozytorium, a potem wykonaj cp .env.example .env i uzupełnij puste wartości.