Format pliku .env: reguły składni, na których się wykładasz
Przewodnik po formacie pliku .env
Format pliku .env: składnia, cudzysłowy, komentarze, wiele linii | We.Inc
Reguły składni pliku .env dotyczące cudzysłowów, komentarzy, pustych wartości i kluczy wieloliniowych, miejsca, w których dotenv i Docker Compose się różnią, oraz linter, do którego wkleisz swój plik.
Plik .env to zwykły tekst z jedną parą KEY=value w każdej linii. Puste linie są pomijane, a linie zaczynające się od # to komentarze. Ujmij wartość w cudzysłów, gdy ma spacje na początku lub końcu, znak # albo podziały linii. Nie istnieje jeden standard, więc dotenv dla Node i Docker Compose odczytują kilka przypadków brzegowych inaczej.
Jak dotenv odczytuje typowe linie
- Linia
- Otrzymana wartość
- Dlaczego
- PORT=3000
- Podstawowa para, zawsze ciąg znaków
- EMPTY=
- (pusty ciąg)
- Puste wartości stają się pustymi ciągami
- NAME= Ada
- Wartości bez cudzysłowu są przycinane z obu stron
- NAME=" Ada "
- Cudzysłów zachowuje spacje
- HASH="a#b"
- Znak # wewnątrz cudzysłowu nie jest komentarzem
- MSG="one\ntwo"
- dwie linie
- Podwójny cudzysłów zamienia \n w podział linii
Większość zepsutych plików .env psuje się na tych samych kilku szczegółach: znak # w haśle, klucz prywatny wklejony w kilku liniach albo cudzysłów, który nigdy się nie zamyka. Wklej swój plik do lintera, aby zobaczyć, co dotenv odczyta dla każdego klucza i gdzie Docker Compose odczyta to inaczej.
- Wklej zawartość pliku .env do pola albo edytuj przykład, który już tam jest.
- Każdy klucz jest wypisany z wartością, jaką dotenv przekaże Twojemu programowi po obsłużeniu cudzysłowów i komentarzy.
- Uwagi wskazują prawdziwe problemy (brak znaku =, niezamknięty cudzysłów, powtórzony klucz) oraz ostrzeżenia o przenośności.
- Popraw linię, zobacz, jak uwaga znika, a potem skopiuj oczyszczony plik z powrotem do projektu.
- Każdą wartość zawierającą # ujmij w cudzysłów. dotenv zaczyna komentarz od pierwszego # w wartości bez cudzysłowu, więc hasło takie jak abc#123 po cichu staje się abc.
- Trzymaj się nazw UPPER_CASE złożonych z liter, cyfr i podkreśleń, które nie zaczynają się od cyfry. Akceptuje je każda powłoka i każde narzędzie.
- Dodaj .env do .gitignore i commituj .env.example z tymi samymi kluczami i przykładowymi wartościami, aby nowe osoby w zespole wiedziały, co uzupełnić.
- Nie oczekuj, że $OTHER zostanie rozwinięte w zwykłym dotenv. Jego README odsyła do osobnego narzędzia do rozwijania zmiennych, a Docker Compose rozwija je za Ciebie.
Najczęściej zadawane pytania
Czy istnieje oficjalna specyfikacja pliku .env?
Nie. Format wyrósł z przypisań zmiennych w powłoce i każdy loader dokumentuje własne reguły. Pakiet dotenv dla Node i Docker Compose publikują swoje i zgadzają się co do podstaw: linie KEY=value, komentarze # i wartości w cudzysłowie.
Czy wartości w pliku .env powinny być w cudzysłowie?
Tylko wtedy, gdy jest to potrzebne. Cudzysłów jest wymagany dla wartości ze znakiem #, spacjami na początku lub końcu albo podziałami linii. W Compose używaj pojedynczego cudzysłowu, gdy chcesz, by $ pozostał dosłowny, bo wartości w pojedynczym cudzysłowie nie są tam interpolowane.
Jak zapisać wartość wieloliniową, na przykład klucz prywatny?
Ujmij ją w podwójny cudzysłów i zachowaj prawdziwe podziały linii, co dotenv obsługuje od wersji 15.0.0. Możesz też trzymać ją w jednej linii i pisać \n w miejscu każdego podziału, bo wartości w podwójnym cudzysłowie zamieniają \n w nową linię.
Czy mogę dodać komentarz na końcu linii?
Tak, ostrożnie. dotenv traktuje # bez cudzysłowu jako początek komentarza. Docker Compose robi tak tylko wtedy, gdy przed # stoi spacja, więc KEY=a#b daje a#b w Compose, ale a w dotenv. Dla bezpieczeństwa zostawiaj spację przed komentarzami w linii.
Czy dotenv nadpisuje zmienne, które są już ustawione?
Nie. Domyślnie dotenv nigdy nie zmienia zmiennej, która już istnieje w środowisku, więc wygrywa wartość ustawiona przez powłokę lub hosting. Przekaż opcję override ustawioną na true, jeśli chcesz, aby plik je zastępował.
Gdzie dotenv i Docker Compose się rozchodzą
- Komentarze w linii to klasyczna pułapka. Compose wymaga białego znaku przed # w wartości bez cudzysłowu, a dotenv ucina wartość na pierwszym napotkanym #. Oba ignorują # znajdujący się wewnątrz cudzysłowu.
- Drugą różnicą jest rozwijanie zmiennych. Compose zastępuje $VAR i ${VAR} w wartościach bez cudzysłowu i w podwójnym cudzysłowie, a wartości w pojedynczym cudzysłowie zostawia nietknięte. Zwykły dotenv zwraca znak dolara i nazwę dokładnie tak, jak zostały zapisane.
Jak dbać o bezpieczeństwo plików .env
- Plik .env zwykle zawiera hasła do bazy danych i klucze API, więc traktuj go jak każdy inny sekret. Trzymaj go poza systemem kontroli wersji, nadaj mu ścisłe uprawnienia na serwerach i zmieniaj każdą wartość, która kiedykolwiek przez pomyłkę trafiła do commita.
- Na produkcji preferuj ustawienia sekretów swojego hostingu. Ten plik to wygoda przy lokalnym developmencie, a nie sejf.
dotenv i Docker Compose obok siebie
Ta sama linia odczytana przez dwa loadery
- Linia
- dotenv (Node)
- Docker Compose
- x#y (brak spacji przed #)
- A=x #note
- A='$HOME'
- $HOME
- $HOME (pojedynczy cudzysłów jest dosłowny)
- A="$HOME"
- $HOME
- wartość HOME
- A="x\ty"
- x\ty
- x, tabulator, potem y
- A="x\ny"
- dwie linie
- dwie linie
Przykłady do skopiowania
Uporządkowany .env.example
Te same klucze co w prawdziwym pliku, bezpieczne przykładowe wartości, komentarze objaśniające każdą grupę. Commituj ten plik, nigdy prawdziwy .env.
Wczytanie go w Node
config() domyślnie czyta .env z bieżącego katalogu roboczego. Wartości już obecne w środowisku pozostają bez zmian.
Linter .env
Wklej swój plik .env
Co dotenv odczytuje z każdej linii
Linia
Klucz
Wartość
Uwagi
(pusty ciąg)
Odczytane klucze: {n}, z uwagami: {v}
Nie znaleziono jeszcze kluczy.
Brak znaku =, więc ta linia jest ignorowana.
Klucz zawiera spację. Usuń ją, inaczej linia nie zostanie odczytana tak, jak oczekujesz.
Nazwa nie jest przenośna. Powłoki oczekują liter, cyfr i podkreśleń, bez cyfry na początku.
Cudzysłów nigdy się nie zamyka, więc reszta pliku może zostać wchłonięta do tej wartości.
Ustawiony także w linii {n}. Zostaw jeden, aby nikt nie musiał zgadywać, który wygrywa.
dotenv zatrzymuje się na #, ale Docker Compose go zachowuje, bo nie poprzedza go spacja. Ujmij wartość w cudzysłów.
Zawiera $. Docker Compose go rozwija; zwykły dotenv zostawia go w zapisanej postaci.
Obejmuje kilka linii wewnątrz cudzysłowu.
Rozpocznij darmowy okres próbny · 7 dni za darmo, dziś $0
Powiązane: Poradniki
- Express.js tutorial
- Parametry UTM na Facebooku dla reklam Meta
- Nawigacja fasetowa a SEO
- Przykłady stron FAQ i szablon do skopiowania
- Jak pisać strony FAQ cytowane w odpowiedziach AI
- FastAPI WebSocket
- Rozmiary favicony i kod, który ją dodaje
- Figma do kodu
Produkt
Dla kogo
- Dla agencji
- Dla freelancerów
- Dla firm hostingowych
- Dla platform SaaS
- Dla startupów
- Usługi finansowe
- Rozwiązania dla ochrony zdrowia
Funkcje
Zasoby
- Blog
- Centrum pomocy
- Darmowe narzędzia dla firm
- Free UI Components
- Szablony
- Kolekcje szablonów
- Przykłady stron
- Poradniki
- Porównania
- Alternatywy
- Najlepsze
- Recenzje
- Przewodniki po cenach
- Zastosowania
- Słownik i poradniki
- Integracje
- Dla programistów
- Benchmark
- Windows App