Twoja aplikacja potrzebuje adresu URL bazy danych. Na Twoim laptopie jest to lokalna baza danych, w CI jednorazowa, a na produkcji klaster zarządzany. Zakodowanie dowolnego z nich oznacza zmianę kodu dla każdego środowiska. Zmienne środowiskowe rozwiązują ten problem. Kod brzmi DATABASE_URL, a każde środowisko dostarcza własną wartość.

Pomysł ten jest kluczowy dla metody aplikacji Twelve-Factor, która mówi, że konfiguracja różniąca się w zależności od wdrożenia należy do środowiska. Przetestowaliśmy poniższe zachowanie w Pythonie 3.13 w systemie Windows. Wszystkie pokazane dane wyjściowe pochodzą z tego przebiegu.

Co to są zmienne środowiskowe?

Każdy działający proces ma zestaw nazwanych wartości tekstowych zwanych jego środowiskiem. Znane przykłady to PATH, które mówią powłoce, gdzie znaleźć programy, oraz HOME lub USERPROFILE. Twoja własna aplikacja może korzystać z tego samego mechanizmu dla ustawień takich jak APP_PORT, LOG_LEVEL lub DATABASE_URL.

Ustawianie zmiennych środowiskowych

Trwają one tylko dla bieżącej sesji terminala. Aby uczynić je trwałymi, dodaj je do profilu powłoki, takiego jak ~/.bashrc lub, w systemie Windows, użyj ustawień środowiska systemowego lub setx. W przypadku aplikacji zwykle lepiej jest dostarczyć je na etapie wdrażania, niż ustawiać je w całym systemie.

Odczytywanie ich w kodzie

import os

port = os.environ.get("APP_PORT", "8000")   # default if missing
print(port)                                  # 8000

db = os.environ["DATABASE_URL_MISSING_DEMO"]
# KeyError: 'DATABASE_URL_MISSING_DEMO'

Użyj .get() z wartością domyślną dla ustawień opcjonalnych. W przypadku ustawień, bez których aplikacja nie może działać, użyj nawiasów kwadratowych, które podnoszą KeyError. Inne języki są podobne: process.env.APP_PORT w Node.js, System.getenv("APP_PORT") w Javie i os.Getenv("APP_PORT") w Go.

Wszystko jest sznurkiem

To przyciąga ludzi w każdym języku. Ustawiliśmy port, a następnie dodaliśmy do niego „1”:

os.environ["APP_PORT"] = "8080"
port = os.environ["APP_PORT"]
print(type(port).__name__, repr(port), port + "1")
# str '8080' 80801

os.environ["APP_PORT"] = 8080
# TypeError: str expected, not int

Wartość wróciła jako tekst, a dodanie spowodowało 80801, a nie 8081. Konwertuj jawnie, jak w int(os.environ["APP_PORT"]). Wartości logiczne są gorsze:

os.environ["DEBUG"] = "false"
print(bool(os.environ["DEBUG"]))   # True

Każdy niepusty ciąg znaków jest prawdziwy w Pythonie, więc "false" stało się True. Tryb debugowania zostałby włączony w środowisku produkcyjnym. Celowo analizuj wartości logiczne:

def env_bool(name, default=False):
    value = os.environ.get(name)
    if value is None:
        return default
    return value.strip().lower() in {"1", "true", "yes", "on"}

env_bool("DEBUG")                   # False
env_bool("NOT_SET", default=True)   # True

W jaki sposób procesy je dziedziczą

Proces potomny otrzymuje kopię środowiska swojego rodzica. Rozpoczęliśmy procesy potomne w Pythonie, aby zobaczyć to:

child sees: 8080 inherited     # default: full copy of the parent's environment
child sees: 9000 None          # given a custom env: only what we passed
parent sees child var: None    # a child's changes never flow back

Następują trzy lekcje praktyczne. Eksportowane zmienne są widoczne dla każdego uruchomionego programu, w tym dla skryptów, których nie napisałeś, co ma znaczenie dla tajemnic. Przekazanie niestandardowego środowiska zastępuje całość, więc uwzględnij wszystko, czego potrzebuje dziecko. Skrypt nie może zmienić zmiennych powłoki nadrzędnej, dlatego narzędzia proszą o source plik zamiast go uruchomić.

pliki .env

Ręczne wpisywanie wielu zmiennych jest uciążliwe, dlatego większość projektów przechowuje lokalne wartości rozwojowe w pliku .env:

# local development only
APP_PORT=8080
DATABASE_URL="postgres://dev:devonly@localhost:5432/shop"
FEATURE_SEARCH=true

Biblioteki takie jak python-dotenv i dotenv dla Node.js ładują ten plik podczas uruchamiania. Node.js 20.6 i nowsze wersje mogą również ładować go natywnie za pomocą --env-file. Aby zobaczyć pomysł, napisaliśmy mały parser, który zamienił powyższy plik na:

{'APP_PORT': '8080',
 'DATABASE_URL': 'postgres://dev:devonly@localhost:5432/shop',
 'FEATURE_SEARCH': 'true'}

Wykorzystaj w praktyce prawdziwą bibliotekę. Obsługuje cytowanie, znaki ucieczki, komentarze i wartości wieloliniowe, które nasza 10-liniowa wersja ignoruje. Domyślnie większość programów ładujących dotenv nie nadpisuje zmienne, które są już ustawione, więc wartości rzeczywistego środowiska wygrywają z plikiem. Zwykle tego właśnie chcesz.

Sprawdź konfigurację przy uruchomieniu

Brakująca zmienna powinna natychmiast zatrzymać aplikację i dać jasny komunikat, a nie powodować mylącego błędu godzinę później. Podczas ładowania sprawdziliśmy wymagane ustawienia:

REQUIRED = ["DATABASE_URL", "SECRET_KEY"]

def check_required(env):
    missing = [k for k in REQUIRED if not env.get(k)]
    if missing:
        raise SystemExit(f"Missing required settings: {', '.join(missing)}")

# Missing required settings: SECRET_KEY

Wpisane biblioteki konfiguracyjne idą dalej. Ustawienia Pydantic w Pythonie, zod lub envalid w Node.js oraz właściwości konfiguracyjne Springa w Javie konwertują typy i zgłaszają każdy problem na raz.

Zmienne środowiskowe i sekrety

Zmienne środowiskowe są powszechnym sposobem przekazywania do aplikacji sekretów, takich jak klucze API, i są znacznie lepsze niż kodowanie ich na stałe. Mają słabe strony, o których warto wiedzieć:

• Jak pokazał nasz test, procesy potomne dziedziczą je.
• Mogą pojawiać się w raportach o awariach, stronach debugowania i dziennikach, które zrzucają środowisko.
• W niektórych systemach inne procesy uruchamiane przez tego samego użytkownika mogą je odczytać.

W przypadku produkcji wiele zespołów przechowuje sekrety w dedykowanym menedżerze, takim jak HashiCorp Vault, AWS Secrets Manager, Azure Key Vault lub Google Secret Manager, i wprowadza je w czasie wykonywania. Niektórzy wolą montować sekrety w postaci plików zamiast zmiennych. Tak czy inaczej, nigdy nie drukuj konfiguracji w dziennikach i zmieniaj wszelkie sekrety, które kiedykolwiek zostały przekazane Gitowi, nawet po usunięciu ich z historii.

W Dockerze i CI

# Docker (not run for this article)
docker run -e APP_PORT=8080 --env-file .env.production myapp

# GitHub Actions (not run for this article)
env:
  APP_PORT: 8080
  API_KEY: ${{ secrets.API_KEY }}

Platformy CI przechowują zaszyfrowane sekrety i maskują je w dziennikach. Unikaj umieszczania sekretów w obrazach Dockera za pomocą ENV w pliku Dockerfile, ponieważ pozostają one czytelne w warstwach obrazu. Pełne konfiguracje znajdziesz w naszym samouczku Docker Compose i przewodniku CI/CD dotyczącym akcji GitHub Actions.

Najlepsze praktyki

• Używaj wyraźnych, wielkich nazw z przedrostkiem, na przykład SHOP_DB_URL.
• Przeczytaj całą konfigurację w jednym module, przekonwertuj tam typy i sprawdź przy uruchomieniu.
• Podaj bezpieczne ustawienia domyślne tylko dla ustawień niewrażliwych.
• Trzymaj .env z dala od Git i utrzymuj .env.example.
• Użyj menedżera wpisów tajnych w środowisku produkcyjnym dla poufnych wartości.
• Dokumentuj każdą zmienną, jej typ i przykładową wartość.

Debugowanie problemów ze zmiennymi środowiskowymi

Jeśli aplikacja zachowuje się tak, jakby brakowało jakiegoś ustawienia, wykonaj następujące kontrole w podanej kolejności:

1. Czy jest ustawione w dobrym miejscu? Zmienna wyeksportowana w jednej zakładce terminala nie istnieje w innej, lub w usłudze uruchomionej przez system.
2. Czy aplikacja została uruchomiona ponownie? Działający proces zachowuje środowisko, w którym został uruchomiony. Późniejsza zmiana zmiennej nie przyniesie efektu aż do ponownego uruchomienia.
3. Czy nazwa jest dokładna? W nazwach w systemie Linux i macOS rozróżniana jest wielkość liter, więc App_Port i APP_PORT to różne zmienne. Windows traktuje je tak samo.
4. Czy plik .env zastępuje go, czy jest ignorowany? Sprawdź, czy moduł ładujący zastępuje istniejące wartości i który plik faktycznie czyta.
5. Czy występują przypadkowe cudzysłowy lub spacje? Wartość skopiowana ze spacją na końcu lub dodatkowymi cudzysłowami może nie zostać przeanalizowana lub dopasować w sposób trudny do wykrycia.

Aby zobaczyć, co naprawdę otrzymał proces, wypisz nazwy zmiennych, nigdy wartości sekretów. W systemach Linux i macOS printenv wyświetla listę bieżącego środowiska powłoki, a w PowerShell Get-ChildItem Env: robi to samo. Wewnątrz kontenera, przejście od env do docker exec pokazuje widok kontenera, który często różni się od widoku twojej własnej powłoki.

Ostatnia wskazówka: podczas uruchamiania zapisz jedną linię zawierającą listę ustawień opcjonalnych, które korzystają z wartości domyślnych. To nic nie kosztuje, a odpowiada na większość pytań: „dlaczego to robi?” pytania od razu.

Podsumowanie

Zmienne środowiskowe są proste, ale skrywają kilka pułapek: wszystko jest ciągiem znaków, dzieci je dziedziczą i tajemnice mogą przez nie wyciekać. Traktuj je jako dane wejściowe do swojej aplikacji. Przeczytaj je w jednym miejscu, przekonwertuj i zweryfikuj je wcześniej, a także zachowaj prawdziwe tajemnice przed zatwierdzonymi plikami.

Najczęstsze pytania

Ucz się dalej