Compose Clinic
Guias / Variáveis · 01

Variáveis · 01

O .env foi lido. Por que a variável não aparece no serviço?

A tag da imagem resolvida mostra que o Compose leu o .env. Isso não significa que todas as variáveis entraram no ambiente do serviço.

Modelo verificadoCompose 5.3.012 set 20265 min

A correção

Declare a variável em environment ou carregue intencionalmente um arquivo de ambiente do serviço com env_file. Uma chave solta no .env não cria essa atribuição no modelo do serviço.

Confira primeiro a configuração resolvida. É possível identificar essa diferença sem criar ou reiniciar um container. Use uma pasta de teste e os valores fictícios abaixo.

Reproduza a entrada ausente

Crie os dois arquivos na mesma pasta.

# .env
CC_IMAGE_TAG=1.37
CC_ONLY=not-automatically-injected
# compose.yaml
services:
  probe:
    image: busybox:${CC_IMAGE_TAG}
docker compose config --format json

No nosso teste com Compose 5.3.0, services.probe.image ficou como busybox:1.37. Já services.probe.environment não apareceu. O primeiro valor foi usado na construção do modelo; o segundo não foi atribuído ao serviço.

Esse resultado descreve o modelo do Compose. Não é uma inspeção do ambiente de um container em execução nem das variáveis definidas pela própria imagem.

Passe o valor de forma explícita

services:
  probe:
    image: busybox:${CC_IMAGE_TAG}
    environment:
      CC_ONLY: ${CC_ONLY:?CC_ONLY must be set}

Execute novamente config. Agora o modelo inclui:

environment:
  CC_ONLY: not-automatically-injected

A expressão obrigatória evita que um valor ausente ou vazio passe silenciosamente. Em outro teste, uma entrada vazia terminou com erro contendo CC_EMPTY must be set.

Para fornecer várias variáveis do aplicativo, você também pode criar um arquivo dedicado e declará-lo em env_file. Prefira separar configurações do aplicativo de opções usadas apenas para montar o projeto.

Confira a camada certa

  1. A tag não foi resolvida: confira a origem da interpolação e o caminho do arquivo.
  2. A variável não está no modelo: revise a atribuição ao serviço.
  3. O modelo está certo, mas o aplicativo está diferente: verifique o container implantado e as regras do próprio aplicativo.

Nossa prova não executou up, reinício, download de imagem ou acesso ao daemon. Antes de aplicar a mudança em um projeto real, revise o diff e siga o processo de publicação desse projeto. Para desfazer a alteração no teste, restaure o mapeamento anterior.

Em um projeto real, config pode mostrar segredos resolvidos. Não publique essa saída. A prova disponível neste site usa apenas valores de demonstração.

Fontes e prova

Documentação consultada em 12.09.2026. Prova própria:

Continue a investigação