Вашему приложению нужен URL-адрес базы данных. На вашем ноуте это локальная база данных, в CI одноразовая, а в продакшене управляемый кластер. Жесткое кодирование любого из них означает изменение кода для каждой среды. Переменные среды решают эту проблему. Код читается как DATABASE_URL, и каждая среда предоставляет свое собственное значение.

Эта идея является центральной в методе двенадцатифакторного приложения, который утверждает, что конфигурация, которая варьируется в зависимости от развертывания, принадлежит среде. Мы протестировали приведенное ниже поведение с помощью Python 3.13 в Windows. Все показанные выходные данные взяты из этого прогона.

Что такое переменные среды?

Каждый запущенный процесс имеет набор именованных текстовых значений, называемых его средой. Знакомые примеры: PATH, который сообщает оболочке, где найти программы, и HOME или USERPROFILE. Ваше собственное приложение может использовать тот же механизм для таких настроек, как APP_PORT, LOG_LEVEL или DATABASE_URL.

Установка переменных среды

Они действуют только в течение текущего сеанса терминала. Чтобы сделать их постоянными, добавьте их в профиль оболочки, например ~/.bashrc, или, в Windows, используйте настройки системной среды или setx. Что касается приложений, обычно лучше предоставлять их во время развертывания, а не устанавливать для всей системы.

Чтение их в коде

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'

Используйте .get() со значением по умолчанию для дополнительных настроек. Используйте квадратные скобки, поднимающие KeyError, для настроек, без которых приложение не может работать. Другие языки аналогичны: process.env.APP_PORT в Node.js, System.getenv("APP_PORT") в Java и os.Getenv("APP_PORT") в Go.

Все это строка

Это ловит людей на каждом языке. Мы установили порт, а затем добавили к нему «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

Значение вернулось в виде текста, и при добавлении получилось 80801, а не 8081. Преобразуйте явно, как в int(os.environ["APP_PORT"]). Булевы значения хуже:

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

Любая непустая строка в Python является истинной, поэтому "false" стало True. Режим отладки был бы включен в производстве. Разбирайте логические значения намеренно:

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

Как процессы их наследуют

Дочерний процесс получает копию среды своего родителя. Чтобы увидеть это, мы запустили дочерние процессы Python:

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

Далее следуют три практических урока. Экспортируемые вами переменные видны каждой запускаемой вами программе, включая сценарии, которые вы не писали, что важно для секретов. Передача пользовательской среды заменяет все, поэтому включите все, что нужно ребенку. А сценарий не может изменять переменные своей родительской оболочки, поэтому инструменты просят вас source открыть файл вместо его запуска.

.env-файлы

Вводить множество переменных вручную утомительно, поэтому большинство проектов сохраняют локальные значения разработки в файле .env:

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

Такие библиотеки, как python-dotenv и dotenv для Node.js, загружают этот файл при запуске. Node.js 20.6 и более поздние версии также могут загружать его с помощью --env-file. Чтобы увидеть эту идею, мы написали крошечный парсер, который превратил приведенный выше файл в:

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

Используйте настоящую библиотеку на практике. Он обрабатывает кавычки, escape-символы, комментарии и многострочные значения, которые игнорирует наша 10-строчная версия. По умолчанию большинство загрузчиков dotenv не переопределяют уже установленные переменные, поэтому реальные значения среды имеют преимущество над файлом. Обычно это то, чего вы хотите.

Проверка конфигурации при запуске

Отсутствующая переменная должна немедленно остановить приложение с четким сообщением, а не вызывать запутанную ошибку через час. При загрузке мы проверили необходимые настройки:

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

Библиотеки типизированной конфигурации идут дальше. Настройки Pydantic в Python, zod или envalid в Node.js и свойства конфигурации Spring в Java — все они преобразуют типы и сообщают обо всех проблемах одновременно.

Переменные среды и секреты

Переменные среды — это распространенный способ передачи секретов, таких как ключи API, в приложение, и они намного лучше, чем их жесткое кодирование. У них есть слабые стороны, о которых следует знать:

• Дочерние процессы наследуют их, как показал наш тест.
• Они могут появляться в отчетах о сбоях, страницах отладки и журналах, которые выгружают среду.
• В некоторых системах их могут читать другие процессы, запускаемые тем же пользователем.

В производстве многие команды хранят секреты в специальном менеджере, таком как HashiCorp Vault, AWS Secrets Manager, Azure Key Vault или Google Secret Manager, и внедряют их во время выполнения. Некоторые предпочитают монтировать секреты в виде файлов, а не переменных. В любом случае, никогда не печатайте конфигурацию в журналах и не меняйте любой секрет, который когда-либо был передан в Git, даже после того, как вы удалили его из истории.

В Докере и 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 }}

Платформы CI хранят секреты в зашифрованном виде и маскируют их в журналах. Избегайте включения секретов в образы Docker с помощью ENV в файле Dockerfile, поскольку они остаются читаемыми в слоях изображения. Подробные настройки см. в нашем руководстве по Docker Compose и руководстве по GitHub Actions CI/CD.

Лучшие практики

• Используйте понятные имена в верхнем регистре с префиксом, например SHOP_DB_URL.
• Прочтите всю конфигурацию в одном модуле, преобразуйте там типы и проверьте при запуске.
• Предоставляйте безопасные значения по умолчанию только для неконфиденциальных настроек.
• Держите .env вне Git и сохраняйте .env.example.
• Используйте диспетчер секретов в производстве для конфиденциальных значений.
• Задокументируйте каждую переменную, ее тип и пример значения.

Отладка проблем с переменными среды

Если приложение ведет себя так, как будто какой-то параметр отсутствует, выполните следующие проверки по порядку:

1. Правильно ли она установлена? Переменная, экспортированная в одну вкладку терминала, не существует в другой или в службе, запущенной системой.
2. Приложение было перезапущено? Запущенный процесс сохраняет среду, из которой он был запущен. Последующее изменение переменной не имеет никакого эффекта до перезапуска.
3. Точно ли имя? В Linux и macOS имена чувствительны к регистру, поэтому App_Port и APP_PORT — это разные переменные. Windows рассматривает их одинаково.
4. Файл .env переопределяет его или игнорируется? Проверьте, переопределяет ли ваш загрузчик существующие значения и какой файл он на самом деле читает.
5. Есть ли случайные кавычки или пробелы? Значение, скопированное с конечным пробелом или дополнительными кавычками, может не поддаваться анализу или не сопоставляться, что трудно обнаружить.

Чтобы увидеть, что на самом деле получил процесс, выведите имена переменных, а не значения секретов. В Linux и macOS printenv перечисляет текущую среду оболочки, а в PowerShell Get-ChildItem Env: делает то же самое. Внутри контейнера выполнение команд с env по docker exec показывает вид контейнера, который часто отличается от представления вашей собственной оболочки.

Последний совет: при запуске запишите одну строку, в которой указано, какие дополнительные настройки используют значения по умолчанию. Это ничего не стоит и отвечает большинству вопросов: «Почему он это делает?» вопросы сразу.

Итоги

Переменные среды просты, но они скрывают несколько ловушек: все является строкой, дети наследуют их, и через них может просачиваться секрет. Рассматривайте их как входные данные для вашего приложения. Читайте их в одном месте, преобразуйте и проверяйте на ранних стадиях и храните настоящие секреты в файлах, которые будут зафиксированы.

Часто задаваемые вопросы

Продолжайте учиться