Почему Docker Compose не передаёт переменную из файла .env в контейнер

#Что означает ошибка и при каких условиях возникает

Файл .env рядом с compose.yaml может подставлять значения в конфигурацию Compose, но не добавляет их автоматически в окружение приложения. Проверьте путь и environment. Нужно различать интерполяцию ${NAME} в YAML, передачу значений через services.environment и services.env_file, а также переменные окружения уже созданного контейнера.

#Как различить причины

#Пошаговая диагностика и исправление

1. Определите имя переменной без публикации её значенияОткройте проект в VS Code («Файл» → «Открыть папку») и найдите compose.yaml и .env. Для учебного примера используйте только несекретную переменную APP_MODE=development; если речь о пароле или токене, не выводите их в консоль и не присылайте в журналы — для рабочих секретов используйте механизм secrets. Запишите название переменной, а не конфиденциальное значение.
2. Проверьте путь запуска ComposeОткройте терминал в каталоге, содержащем compose.yaml (Windows PowerShell, Терминал macOS/Linux или встроенный VS Code). Выполните docker compose version и docker compose config -q. Если команда сообщает, что файл не найден, перейдите в верный каталог через cd или укажите явный -f. Когда используются -f, --project-directory либо --env-file, учитывайте, что правила поиска .env зависят от параметров запуска.
3. Отличите подстановку значений от окружения контейнераВыполните docker compose config --environment только в безопасном тестовом проекте, не содержащем секретов: эта команда показывает значения, использованные для подстановки. Отдельно посмотрите docker compose config и найдите в конкретной службе секцию environment. Наличие APP_MODE в выводе --environment ещё не доказывает, что программа увидит APP_MODE — нужен services.environment либо services.env_file.
4. Передайте переменную приложению явноДля варианта с подстановкой в compose.yaml добавьте к службе environment: APP_MODE: ${APP_MODE:?APP_MODE is required}. Конструкция :? останавливает обработку конфигурации, если APP_MODE не задана или пуста; таким образом ошибку видно до запуска. Альтернативно можно использовать env_file: ./.env, если у сервиса должны появиться все подходящие значения, но не делайте это без проверки наличия секретов.
5. Проверьте конкурирующие источники значенийЕсли вместо ожидаемого значения выводится другое, сопоставьте среды: переменная из оболочки, явный --env-file, файл .env и services.environment. У Compose есть приоритеты и переопределения. Например, environment в YAML перекрывает env_file сервиса. Не удаляйте неизвестные переменные в рабочей системе; сначала узнайте, откуда они приходят — сценарий CI, оболочка либо служба Docker.
6. Пересоздайте только отдельный тестовый контейнерВ новой папке создайте пару файлов из примера. В терминале выполните docker compose config -q, затем docker compose up -d. Если вы исправили APP_MODE в .env, повторите docker compose up -d --force-recreate именно в тестовой папке. На рабочем сервисе пересоздание вызывает кратковременный перерыв и может затронуть данные, поэтому требуется отдельное согласование.
7. Убедитесь, что приложение получает правильное несекретное значениеВ учебном проекте выполните docker compose exec app printenv APP_MODE; ожидается development. Если exec сообщает, что контейнер не запущен, посмотрите docker compose ps -a и docker compose logs app. Если вместо development пусто, проверьте именно services.environment; если значение неожиданное, проверьте источники из предыдущего шага.
8. При сохранении проблемы сравните окончательную конфигурацию с контейнеромКоманда docker compose config показывает итоговую модель, а docker compose exec app printenv APP_MODE — окружение действующего процесса в тестовом контейнере. Если модель правильная, но процесс старый, пересоздайте его после сохранения важных данных и согласования перерыва. Если модель уже неверная, проблема раньше — в файлах или приоритете переменных; не переустанавливайте Docker.
9. Команды для отдельных ситуацийВыберите только подходящий вариант. Это не одна последовательность: часть команд диагностирует проблему, а часть меняет настройки или данные.
   Выберите подходящий вариант — это не команды для последовательного выполнения

   Вариант 1Выполнить в каталоге с compose.yaml.

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Выполнить в каталоге с compose.yaml. Эти команды проверяют наличие Compose и корректность конфигурации; не печатают значения переменных.

   docker compose version

   docker compose config -q

   Вариант 2Только в учебном проекте без секретов: обе команды могут показать конфиденциальные значения!

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Только в учебном проекте без секретов: обе команды могут показать конфиденциальные значения! Не отправляйте полный вывод в чат или системы заявок.

   docker compose config --environment

   docker compose config

   Вариант 3В отдельной тестовой папке.

   Linux · Терминал (Bash)С осторожностьюКопировать всёВыделить

   В отдельной тестовой папке. Первая команда создаёт контейнер, вторая выводит несекретное значение APP_MODE; для проверки паролей таким способом не пользуйтесь.

   docker compose up -d

   docker compose exec app printenv APP_MODE

   Команда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.

#Минимальный пример для отдельного тестового проекта

APP_MODE=development

services:
  app:
    image: alpine:3.20
    command: ["sh", "-c", "sleep 3600"]
    environment:
      APP_MODE: ${APP_MODE:?APP_MODE is required}

#Как проверить результат и что делать, если проблема осталась

Успех — учебный docker compose exec app printenv APP_MODE выводит development, а приложение получает требуемый параметр. Если не получается, отдельно проверьте имя ключа, расположение .env, параметры запуска и приоритет services.environment/ env_file; не публикуйте конфиденциальные значения.