Ошибки и коды · Инструкция
Docker Compose: переменная не подставляется — что делать
Если `${VAR}` становится пустой строкой или неожиданным значением, сначала проверяйте не контейнер, а этап interpolation Compose. Shell, `--env-file` и стандартный `.
Короткий ответ
Сначала выполните `docker compose config --environment` и `docker compose config`: так видно, какие значения Compose использует для interpolation. Затем проверяйте `.env`, shell и синтаксис `${VAR}`.
Что важно знать про Docker Compose interpolation
Compose подставляет значения до запуска container. Поэтому ошибка может находиться на уровне CLI и project directory, а не в самом приложении. Документированный precedence для interpolation начинается с shell environment, затем `--env-file`, затем стандартного `.env` проекта. Это объясняет случаи, когда правка `.env` не меняет результат из-за значения в shell.
Совет: Начинайте с `docker compose config --environment` — это самый быстрый снимок источников interpolation.
Как найти источник пустой переменной
- Запустите config --environment.
- Проверьте project directory и выбранный env file.
- Сверьте регистр имени и пробелы.
- Для критичной переменной добавьте `${VAR:?required}`.
- Проверьте развернутую модель через config.
- Только затем проверяйте container env.
Предупреждение: Одинарные кавычки и `$$` меняют обработку `$`; используйте их осознанно.
Нюансы: --env-file и config --environment
Для обязательной переменной полезен `${VAR:?error}`: запуск завершится с понятной ошибкой вместо пустого значения. Для default можно использовать `${VAR:-default}`. Одинарные кавычки в `.env` сохраняют значение буквально, а буквальный знак доллара в Compose требует осознанного escaping. Итоговую нормализованную модель всегда проверяйте `docker compose config`.
Важно: Для критичных переменных `${VAR:?ошибка}` лучше тихого запуска с пустым значением.
Пример: fallback и обязательное значение
`${TAG:-dev}` даёт fallback, а `${TAG:?set TAG}` останавливает запуск при отсутствии TAG — это быстрее тихой диагностики неправильного image tag.
Минимальный алгоритм диагностики
Запустите `docker compose config --environment`, затем `docker compose config`. Если нужного значения нет уже здесь, проверяйте shell, путь `.env`, `--env-file`, регистр имени и project directory. Для обязательных значений используйте `${VAR:?message}`; для литерального знака `$` в Compose применяется `$$`.
Если значение есть в config, но нет в приложении
Тогда interpolation сработала, а проблема находится на следующем этапе: `environment`, `env_file`, entrypoint приложения или его собственная конфигурация. Не продолжайте редактировать `.env` вслепую. Сравните environment контейнера с ожидаемым ключом и только затем переходите к настройкам приложения.
Чек-лист interpolation
- `docker compose config --environment` показывает ожидаемый источник и значение переменной.
- `docker compose config` содержит уже подставленное значение там, где оно нужно в модели.
- Для литерального `$` используется `$$`, а quoting соответствует ожидаемой interpolation.
- Если значение теряется только внутри приложения, проверка перенесена на `environment`/`env_file`, а не обратно в `.env`.
Что учитывать
Compose подставляет значения до запуска container. Поэтому ошибка может находиться на уровне CLI и project directory, а не в самом приложении. Документированный precedence для interpolation начинается с shell environment, затем `--env-file`, затем стандартного `.env` проекта. Это объясняет случаи, когда правка `.env` не меняет результат из-за значения в shell.
Источники и проверка
Фактическая часть сверена по первичным источникам (в т.ч. Compose variable interpolation). Пример и формулировки — редакция N1RO на 2026-09-22.