Tutoriais de VPS
Docker Compose não aplica .env: prioridades, recriação e configuração
Separe interpolação, ambiente do contêiner e aplicação; localize sobrescritas, recrie o serviço certo e confira dados sem expor segredos.

Você alterou .env, reiniciou o contêiner e continua vendo chave de API, endereço do banco ou modo antigos. Confira primeiro se o arquivo participa da configuração desse serviço e se o contêiner foi recriado com os valores novos.
.env, a opção --env-file e o campo env_file têm funções diferentes. Siga interpolação do Compose → criação do contêiner → configuração da aplicação. O serviço ilustrativo é app; use o nome real. As verificações usam valores inofensivos, sem imprimir credenciais.
| Sintoma | O que conferir | Próximo passo |
|---|---|---|
| variable is not set | Arquivo ausente ou nome errado | Selecionar o arquivo e conferir ${VAR} |
| config já mostra o valor antigo | Shell, valor fixo ou arquivo de sobrescrita | Identificar a origem dominante |
| config novo, contêiner antigo | Apenas restart ou projeto errado | Confirmar projeto e recriar serviço |
| Contêiner atualizado, página igual | Cache ou variável de compilação | Atualizar aplicação ou compilar conforme documentação |
| Falha no banco após trocar senha | Inicialização e conta existente divergem | Rotação de credenciais do banco |
A referência de restart esclarece que restart não atualiza variáveis do contêiner existente. Confira a configuração antes de recriar.
Suponha que exista .env:
APP_MODE=production
O valor substitui um campo quando o Compose o referencia:
services:
app:
image: alpine:3.22
command: ["sleep", "3600"]
environment:
APP_MODE: "${APP_MODE:?请设置 APP_MODE}"
É um exemplo de diagnóstico sem dados de negócio ou portas públicas. Alpine serve para observar a configuração; não substitua sua imagem de aplicação por ele.
Use --env-file /实际路径/.env.production se o arquivo estiver em outro lugar. Criar .env não injeta automaticamente todas as variáveis em todos os contêineres. Confira interpolação e busca de arquivos.
Você pode referenciar o arquivo dentro do serviço:
services:
app:
image: alpine:3.22
command: ["sleep", "3600"]
env_file:
- ./app.env
APP_MODE=production em app.env entra no ambiente de app. Caminhos relativos partem do arquivo Compose, não necessariamente do diretório do terminal. Veja ambiente do serviço.
Um outro campo com ${APP_MODE} não recebe interpolação apenas porque o serviço contém env_file. Interpolação do projeto e injeção no contêiner são etapas separadas.
Entre no diretório de implantação. O exemplo usa /opt/myapp, compose.yaml e .env.production:
cd /opt/myapp
pwd
ls -la compose.yaml .env.production
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production config --quiet
Substitua os caminhos. config --quiet verifica a análise sem imprimir todos os valores. Para uma variável inofensiva, execute config sem --quiet no terminal privado e encontre o serviço. A saída expandida pode conter senhas e conexões; não a publique inteira.
Se a implantação utiliza vários -f, nome -p fixo ou outro --project-directory, preserve as opções. Alterar -p pode criar outro conjunto de contêineres. 1Panel e Portainer podem guardar ambiente ou Stack próprios; editar um arquivo local não atualiza automaticamente essa origem.
Confira se o shell atual já define a variável. Ele tem prioridade na interpolação; --env-file não força todos os valores. Em um projeto de teste:
APP_MODE=from-shell docker compose --env-file .env config
Mesmo com APP_MODE=production em .env, ${APP_MODE} recebe from-shell. Se produção não deve herdar a variável, confira nome e alcance antes de usar unset APP_MODE nessa sessão e testar novamente.
No serviço, environment tem prioridade sobre env_file:
services:
app:
image: alpine:3.22
command: ["sleep", "3600"]
env_file:
- ./app.env
environment:
APP_MODE: development
Alterar APP_MODE em app.env não substitui o valor explícito em environment. Até um valor vazio pode sobrescrever o arquivo. Confira as chaves, não apenas a string antiga, conforme a prioridade de variáveis.
Outros arquivos Compose também podem sobrescrever o serviço. config só é útil quando as opções correspondem à implantação real.
Confira configuração, montagens persistentes e reversão, e use uma janela de manutenção. Mantenha os mesmos parâmetros e limite a mudança a app:
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production up -d --no-deps app
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production ps app
A referência de up explica que up recria os contêineres afetados e conserva os volumes montados. Uma instância única para brevemente. Dados na camada gravável sem montagem não são persistentes. --no-deps atende quando dependências já funcionam e só a aplicação muda; coordene mudanças de dependências separadamente.
Se o modelo está correto e precisa forçar a recriação:
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production up -d --no-deps --force-recreate app
Isso não corrige prioridades nem recompila automaticamente a imagem. Não precisa executar down primeiro. Evite down -v e apagar volumes como suposta correção do ambiente.
Para uma variável inofensiva, em uma imagem com printenv:
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production exec app printenv APP_MODE
Imagens mínimas podem não ter o programa; use o diagnóstico da aplicação. Não exporte todas as variáveis para conferir uma chave. Depois teste uma requisição de negócio: running não comprova que a aplicação adotou o ajuste.
Confira aspas e interpolação para sinais de dólar. Valores entre aspas simples no .env do Compose são literais. Sintaxe Bash não é universal para arquivos env, e docker run --env-file se comporta de outra forma. Teste primeiro com DEMO_VALUE inofensivo.
Algumas versões exibem $$ escapado na serialização de config. Isso não comprova que o contêiner receberá dois sinais de dólar.
Para expandir a variável apenas no shell do contêiner, use $$:
services:
app:
image: alpine:3.22
environment:
APP_MODE: production
command: ["sh", "-c", "printf '%s\\n' \"$$APP_MODE\"; sleep 3600"]
A especificação de interpolação explica $$. O exemplo chama sh -c explicitamente. Um comando em array não ativa expansão de shell sozinho, e a imagem precisa incluir esse shell.
Confira a aplicação. Laravel pode manter cache; variáveis de frontend podem ser incorporadas na compilação; outros serviços guardam configurações no banco após inicializar. Siga seus procedimentos de cache, compilação e armazenamento.
Uma senha de inicialização não altera uma conta existente. Com volume anterior, rotacione a conta pelo procedimento do banco e sincronize as credenciais da aplicação. Mantenha backup e reversão; apagar o volume para repetir a inicialização destrói dados.
A correção exige config correto com as mesmas opções, contêiner pretendido com os valores novos, requisição de negócio funcionando e dados/dependências saudáveis.
O artigo original verificou quatro YAML com Docker Compose 2.17.3, prioridade do shell, rejeição de valor obrigatório vazio e representação do dólar literal. O padrão era production, a sobrescrita do shell from-shell e a explícita development. Não havia daemon Docker em execução: não foram recriados contêineres nem validada uma carga de produção no VPS.
Para continuar: