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

Produkt

Dla kogo

Funkcje

Zasoby

Firma

Mapa strony