Generator .env.example

Generator .env.example

Plik .env.example to wzór konfiguracji dla nowych środowisk. Zawiera wszystkie potrzebne klucze, ale bez prawdziwych sekretów: każdy programista kopiuje go do .env i uzupełnia lokalnie. Ten generator .env.example robi taki szablon z wklejonego pliku .env: czyści hasła, tokeny i klucze, dodaje komentarze sekcji i wskazuje błędy składni.

Dlaczego .env.example jest ważny?

• nowa osoba w zespole od razu widzi, jakich zmiennych potrzebuje aplikacja,
• zmniejsza ryzyko wycieku sekretów, bo do repozytorium trafia wzór, a nie prawdziwy .env,
• ułatwia wdrożenie i automatyczną konfigurację,
• jest dokumentacją konfiguracji wersjonowaną w repozytorium.

Przykład

Wejście, czyli fragment lokalnego .env:

APP_NAME="Mój sklep"
APP_KEY=base64:Zm9vYmFy
APP_DEBUG=true

DB_HOST=127.0.0.1
DB_PASSWORD=tajne123
DB_URL=mysql://app:tajne123@localhost:3306/sklep

STRIPE_SECRET=sk_test_abc

Wynik przy domyślnych ustawieniach (tryb „Wyczyść sekrety”, komentarze sekcji i nagłówek włączone):

# Skopiuj do .env i uzupełnij wartości

# --- APP ---
APP_NAME="Mój sklep"
APP_KEY=
APP_DEBUG=true

# --- DB ---
DB_HOST=127.0.0.1
DB_PASSWORD=
DB_URL=mysql://app:CHANGE_ME@localhost:3306/sklep

STRIPE_SECRET=

Dobre praktyki

• klucze pisz wielkimi literami z podkreśleniami,
• grupuj zmienne tematycznie (APP_, DB_, MAIL_),
• puste wartości sekretów zostawiaj bez wypełnienia,
• dodaj .env do .gitignore, zawsze.

Jak działa generator .env.example

Generator przyjmuje zawartość pliku .env: po jednej zmiennej w linii, w formacie KLUCZ=wartość albo sam KLUCZ (dostaje wtedy pustą wartość i ostrzeżenie o brakującym „=”). Puste linie i komentarze zaczynające się od # zostają na swoich miejscach, a prefiks export jest zachowany. Nazw kluczy narzędzie nie poprawia: jeśli klucz zawiera myślnik albo zaczyna się cyfrą, zobaczysz ostrzeżenie, a zmianę robisz sam. Na start możesz wybrać szablon Laravel, Node.js, Docker (Postgres, MySQL) albo minimalny.

Sposób obsługi wartości wybierasz w jednym z trzech trybów. „Wyczyść sekrety” dzieli nazwę klucza po znaku _ i zostawia pustą wartość, gdy któryś człon to np. PASSWORD, PASS, SECRET, TOKEN, KEY, SALT albo DSN. Hasło wpisane w adres typu postgres://user:haslo@host zamienia na CHANGE_ME, a hosty, porty i przełączniki zostawia jako przykład. „Wyczyść wszystkie wartości” daje same klucze z pustym „=”, a „Zachowaj wartości” kopiuje je bez zmian, więc wtedy wynik trzeba przejrzeć ręcznie.

Komentarz sekcji, np. # --- DB ---, pojawia się nad grupą kluczy o wspólnym prefiksie przed pierwszym podkreśleniem, jeśli w pliku są co najmniej 2 takie klucze. Pojedyncze klucze, jak STRIPE_SECRET, zostają bez nagłówka. Kolejność linii jest taka jak w pliku źródłowym. Opcja sortowania układa klucze alfabetycznie i oddziela grupy pustą linią, ale usuwa przy tym własne komentarze. Wynik kopiujesz jednym przyciskiem albo pobierasz jako plik .env.example.

Przykład krok po kroku

1. Wklejasz 7 zmiennych z przykładu powyżej: 3 z prefiksem APP_, 3 z prefiksem DB_ i jedną STRIPE_SECRET.
2. Generator sprawdza składnię. Każda linia ma „=”, nazwy są poprawne, a wartość ze spacją stoi w cudzysłowie, więc licznik ostrzeżeń pokazuje 0.
3. Prefiksy APP i DB mają po 3 klucze, więc dostają komentarze sekcji. STRIPE ma 1 klucz i zostaje bez nagłówka. Licznik sekcji: 2.
4. W trybie „Wyczyść sekrety” zmieniają się 4 wartości: APP_KEY (człon KEY), DB_PASSWORD (PASSWORD), STRIPE_SECRET (SECRET) oraz hasło w DB_URL, zamienione na CHANGE_ME. Pozostałe 3 wartości zostają jako przykład.
5. Kafelki pokazują: 7 zmiennych, 4 wyczyszczone wartości, 2 sekcje, 0 ostrzeżeń. W trybie „Wyczyść wszystkie wartości” wyczyszczonych byłoby 7, a w trybie „Zachowaj wartości” 0.

Tabela referencyjna typów zmiennych

Reguły trybu „Wyczyść sekrety”. Liczy się cały człon nazwy między podkreśleniami, a nie fragment słowa.

Praktyczne wskazówki

• Ustal kolejność sekcji raz i trzymaj się jej: diff w repozytorium pokaże wtedy tylko realne zmiany, a nie przestawienie grup. Jeśli zespół nie ma własnego porządku, użyj sortowania alfabetycznego.
• Nie wklejaj produkcyjnych haseł. Narzędzie nie zapisuje treści, ale do zbudowania szablonu wystarczy lokalny .env z wartościami deweloperskimi.
• Dodawaj komentarze nad sekcjami. Generator przenosi komentarze z pliku źródłowego do wyniku (o ile nie włączysz sortowania), więc opis w rodzaju # klucz z panelu Stripe trafi do szablonu.
• Rozdzielaj szablony per środowisko: jeśli staging i produkcja mają inne klucze, utwórz osobny plik dla danego środowiska zamiast nadpisywać główny wzorzec.
• Porównuj .env z .env.example przed commitem. Prosty skrypt lub hook wyłapie klucz, który istnieje lokalnie, ale nie trafił do wzorca.

Ograniczenia generatora

• Sekrety rozpoznaje po nazwie, nie po treści. DBPASSWORD (bez podkreślenia) albo AUTH_HASLO zostaną z wartością, a CACHE_KEY_PREFIX zostanie wyczyszczony, bo zawiera człon KEY. Przed commitem przejrzyj wynik.
• Adres z hasłem bez nazwy użytkownika, np. redis://:haslo@localhost:6379, nie jest rozpoznawany i hasło zostaje w wyniku.
• Nie zna kontekstu frameworka. Szablony Laravel, Node.js i Docker to tylko punkt startowy; generator nie wie, które zmienne są wymagane, i nie usunie zbędnych.
• Nie waliduje wartości: nie sprawdzi, czy port jest liczbą, a adres poprawnym URL-em. Sprawdza tylko składnię linii (brak „=”, niepoprawna nazwa klucza, spacja w wartości bez cudzysłowu, powtórzony klucz) i pokazuje najwyżej 20 ostrzeżeń. Limit wejścia to 20 000 znaków.
• Nie wykryje nieużywanych zmiennych. Jeśli klucz zniknął z kodu, ale nadal jest w danych wejściowych, generator go zachowa.
• Nie zastąpi dokumentacji. Opis formatu i znaczenia zmiennych trzeba dopisać w komentarzach lub w README.