Порядок импорта в Python: .env, VSCode и проблемы с MinIO

Почему Python-проект с .env работает в VSCode, но падает в терминале: порядок импорта, MinIO и переменные окружения. Показываем фикс через ранний load_dotenv.

Проекты на Python, которые зависят от переменных окружения, нередко идеально работают под отладчиком VSCode, но «сыпятся» при запуске из терминала. Если ваш клиент MinIO создаётся во время импорта модуля, а файл .env загружается слишком поздно, расхождение проявляется сразу: VSCode предварительно подгружает .env, а терминал — нет. В итоге получается странная «двойственность»: один и тот же код выглядит надёжным в одном месте и хрупким — в другом.

Reproducing the issue

Корень проблемы — порядок импорта. Если импорт модуля запускает код, которому уже нужны переменные окружения, а загрузка .env происходит позже, запуск из терминала ломается: в момент первого чтения переменные ещё отсутствуют.

# main.py (проблемный вариант)
from shipCheck import boot  # импорт этого модуля запускает код, которому нужны переменные окружения
from pathlib import Path
from dotenv import load_dotenv

env_file = Path(__file__).resolve().parent / ".env"
load_dotenv(dotenv_path=env_file)

Внутри импортируемого модуля клиент MinIO создаётся на верхнем уровне. Эта операция выполняется сразу при импорте, а не при последующих вызовах функций.

# shipCheck/boot.py (выполняется при импорте)
from dataBridge import objstore

client_handle = objstore.StorageClient()  # обращается к окружению во время импорта

Этого достаточно, чтобы запуск из терминала падал, если клиент MinIO требует ключи из окружения, а файл .env ещё не загружен.

Why this happens

В Python импорт модуля немедленно исполняет его верхнеуровневый код. Если этот код пытается получить конфигурацию через переменные окружения, а их ещё нет, вы получите ошибки, похожие на отсутствие настроек или падение инициализации. В VSCode отладчик может заранее подгружать переменные окружения из файла .env до старта вашего скрипта — если это настроено. Значит, к моменту импорта модуля окружение уже заполнено. При обычном запуске в терминале такого предварительного шага нет, поэтому порядок действий становится критически важным.

Отсюда понятно, почему перенос импорта ниже загрузчика dotenv всё исправил. Как только .env загружается первым, инициализация клиента MinIO, происходящая во время импорта, обнаруживает нужные значения.

The fix

Убедитесь, что .env загружается до любых импортов или участков кода, которым требуются переменные окружения. Иными словами, не импортируйте модули, где инициализируется клиент MinIO (или что-либо ещё, что читает переменные окружения), пока не вызвали load_dotenv.

# main.py (исправленный вариант)
from pathlib import Path
from dotenv import load_dotenv

cfg_path = Path(__file__).resolve().parent / ".env"
load_dotenv(dotenv_path=cfg_path)

from shipCheck import boot  # теперь безопасно: переменные окружения уже загружены

Если вы создаёте клиент прямо в этом же файле, действует тот же принцип: сначала загрузите .env, затем создавайте клиент. Здесь имена условные — важен порядок действий.

# storage_app.py (правильный порядок)
from pathlib import Path
from dotenv import load_dotenv
from imgOps import storage_bind

conf_file = Path(__file__).resolve().parent / ".env"
load_dotenv(dotenv_path=conf_file)

minio_session = storage_bind.StorageClient()

Why this is important

Детерминированная загрузка окружения помогает избежать трудноуловимых расхождений между запуском из IDE и «чистым» запуском в терминале. Она также исключает скрытую зависимость от того, как инструменты настраивают ваш процесс. Вы уже проверили рабочую директорию, интерпретатор, sys.path и наличие самого файла .env — всё это действительно может различаться в разных окружениях. В вашем случае решающим оказалось то, что VSCode подставлял значения из .env в процесс ещё до запуска скрипта, скрывая проблему порядка импорта.

Takeaways

Загружайте .env как первый значимый шаг старта программы, а затем импортируйте модули, зависящие от этих переменных. Помните, что VSCode может заранее подгружать .env, из‑за чего ошибки порядка выполнения неочевидны — пока вы не переключитесь на терминал. Если поведение отличается, снимите полный трассбек в терминале, убедитесь, что нужные ключи действительно присутствуют в .env, и проверьте, не добавляет ли IDE дополнительные переменные, которых нет в вашей оболочке. Выравнивание порядка инициализации устраняет расхождение и делает оба сценария запуска согласованными.