Как передавать переменные окружения из Compose в приложение
На этой странице
В Compose есть два разных механизма. Подстановка (interpolation): ${VAR} в YAML заменяется значением из shell или файла .env рядом с compose.yaml — это настройка самого файла. Передача в контейнер: поля environment и env_file создают переменные окружения процесса, которые приложение читает через process.env. Значение в .env само по себе в контейнер не попадает. Для frontend-переменных SPA (VITE_*) есть третий этап — сборка: они вшиваются в бандл и публичны. У Nuxt публичный runtimeConfig (NUXT_PUBLIC_*) читается при запуске сервера, поэтому его передают через environment.
Вопрос
Как Compose передаёт переменные окружения в контейнер и чем .env отличается от env_file?
Три уровня
.env рядом с compose.yaml ──подстановка──▶ ${VAR} в YAML
environment / env_file ──────────────▶ process.env в контейнере
build.args ──────────────▶ ARG при сборке (VITE_*)Подстановка в YAML
# .env
TAG=1.4.0
DB_PASSWORD=dev-passwordservices:
api:
image: ghcr.io/team/api:${TAG:-latest}
environment:
DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app| Синтаксис | Значение |
|---|---|
${VAR} | Значение или пустая строка |
${VAR:-default} | По умолчанию, если не задано или пусто |
${VAR:?message} | Ошибка с сообщением, если не задано |
$$ | Литеральный $ |
Передача в контейнер
services:
api:
env_file:
- .env.api # все переменные файла попадут в контейнер
environment:
NODE_ENV: production # приоритет выше, чем у env_file
PORT: 3000
LOG_LEVEL: # без значения — взять из окружения shellПриоритет (от высшего): docker compose run -e → environment → env_file → ENV в Dockerfile.
Как проверить
docker compose config # YAML после подстановки
docker compose exec api printenv | sort # что реально видит процессПеременные применяются при создании контейнера. После изменения .env нужен docker compose up -d — Compose пересоздаст изменённые сервисы. restart контейнер не пересоздаёт и новые значения не подхватит.
Валидация на старте
import { z } from "zod";
const env = z
.object({
DATABASE_URL: z.string().url(),
PORT: z.coerce.number().default(3000),
JWT_SECRET: z.string().min(32),
})
.parse(process.env);Приложение должно падать сразу с понятной ошибкой, если переменной нет, а не через час на первом запросе.
Frontend-переменные
services:
web:
build:
context: ./web
args:
VITE_API_URL: /api # попадёт в бандл при сборкеenvironment для собранного SPA бесполезен: код уже в браузере. Для Nuxt-сервера наоборот: NUXT_PUBLIC_API_BASE в environment подхватится при старте без пересборки. Всё, что передано в VITE_* или NUXT_PUBLIC_*, видно пользователю.
Секреты
environment удобен для конфигурации, но значения видны в docker inspect и могут попасть в логи. Для паролей в production используют Compose secrets, secret manager платформы или как минимум файл, который не попадает в git, — см. урок про секреты.
Частые ошибки
- Ждать, что переменная из
.envсама появится в контейнере. - Путать
.env(подстановка) иenv_file(передача). - Делать
restartвместоup -dпосле изменения переменных. - Коммитить
.envс реальными паролями вместо.env.example. - Класть секреты во frontend-переменные.
Что важно помнить
.envнастраивает Compose,environment/env_fileнастраивают приложение.docker compose configиprintenv— два шага проверки.- Frontend-переменные — build-time и публичны.
Мини-шпаргалка
${VAR:-default},${VAR:?error}.environment>env_file>ENV.- Изменил переменные →
docker compose up -d. - Проверка:
config,exec printenv. - В git —
.env.example.
Документация
Docker: Environment variables in Compose, Docker: Set environment variables, Docker: Interpolation.