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, wpisz nazwę aplikacji, wskaż bazę danych i zdecyduj, czy projekt używa Redisa oraz poczty. Wynik to plik z pełną listą kluczy pogrupowanych komentarzami sekcji, w którym każdy sekret ma pustą wartość — dokładnie taki, jaki powinien trafić do Gita obok kodu.

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 to narzędzie

Trzy szablony odpowiadają trzem konwencjom nazewniczym: Laravel trzyma parametry bazy w osobnych zmiennych, Node.js i Python w jednym adresie połączenia. Przełączniki Redisa i poczty dokładają własne bloki, a wynik przechodzi przez deduplikację kluczy.

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 i hasła zostają puste, żeby aplikacja krzyknęła przy pierwszym uruchomieniu, zamiast po cichu wystartować na wartości z przykładu. Nieszkodliwe ustawienia — APP_ENV=local, PORT=3000, 127.0.0.1 — warto wpisać, bo skracają start projektu do jednego cp .env.example .env. Adres połączenia generator pokazuje w komentarzu, a wartość zostawia pustą — w repozytorium nie leży wtedy ciąg wyglądający jak działający login z hasłem.

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 wartość tylko wtedy, gdy musi:

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

Prawdziwe sekrety tworzysz później i lokalnie — przyda się generator haseł.

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ę; rozjechany plik uporządkuje sorter zmiennych pliku .env.

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(), a w Django moduł ustawień z konfiguratora settings.py.

Jak korzystać z generatora

1. Wybierz framework — od tego pola zależą nazwy zmiennych i sposób opisu bazy.
2. Wpisz nazwę aplikacji; nazwa z kilku słów dostanie cudzysłowy automatycznie.
3. Wskaż bazę: MySQL, PostgreSQL albo brak zewnętrznej bazy przy SQLite.
4. Zaznacz Redisa i pocztę, jeśli projekt ich używa.
5. Kliknij Generuj .env.example, zapisz wynik w katalogu głównym repozytorium, a potem wykonaj cp .env.example .env i uzupełnij puste wartości.

Najczęściej zadawane pytania