Arquivo .env: para que serve e como criar

Todo projeto tem valores que não pertencem ao código: o token de um bot, a senha do banco, a chave de uma API. Digitar tudo isso no terminal a cada execução cansa, e escrever no código é perigoso. O arquivo .env é a solução comum: um arquivo de texto ao lado do projeto, lido na hora de iniciar.

Na prática, ele é só um jeito de preencher as variáveis de ambiente em desenvolvimento. O sistema operacional não lê o arquivo: quem lê é o runtime (Node.js) ou uma biblioteca (python-dotenv), que copia os pares para o processo.

Qual é a sintaxe de um arquivo .env?#

Uma variável por linha, no formato NOME=valor. Não existe um padrão oficial único, mas as regras abaixo valem no Node.js e no python-dotenv:

DEBUG=false # comentário
DISCORD_TOKEN=cole_o_token_aqui
PORT=3000
DATABASE_URL="postgresql://usuario:senha@localhost:5432/meubanco" # comentário no fim
FRASE='aqui o # não começa comentário'
CHAVE_PRIVADA="linha 1
linha 2"
export NODE_ENV=development

• Nomes usam letras, números e underscore, sem começar por número, em geral em MAIÚSCULAS. No Node.js, my-var e 1_VAR são inválidos.
• Aspas são opcionais, mas necessárias quando o valor tem # ou várias linhas. Valores entre aspas podem ocupar mais de uma linha.
• Tudo é texto. PORT=3000 chega como "3000" e DEBUG=false chega como "false", que em JavaScript e Python é verdadeiro. Converta no código.
• export no começo da linha é aceito e ignorado, o que permite carregar o mesmo arquivo com source .env no shell.

Cuidado também com $ em valores. O Next.js expande $OUTRA_VAR dentro de arquivos .env e exige \$ para um cifrão literal. O python-dotenv só expande a forma ${VAR}.

Como carregar o .env no Node.js?#

As versões recentes do Node.js têm suporte nativo, sem instalar pacote, e a flag --env-file já não é experimental:

node --env-file=.env index.js

// index.js
const token = process.env.DISCORD_TOKEN;
if (!token) throw new Error("DISCORD_TOKEN não definido");

const port = Number(process.env.PORT ?? 3000);
console.log(`Subindo na porta ${port}`);

Se o arquivo não existir, --env-file dá erro. Use --env-file-if-exists=.env, que também vem nas versões recentes do Node.js, quando o arquivo é opcional, por exemplo em produção. Também dá para carregar de dentro do código com process.loadEnvFile('.env'), e util.parseEnv() só interpreta o texto, sem mexer em process.env.

Você pode passar vários arquivos. Os posteriores sobrescrevem os anteriores, mas uma variável já definida no ambiente sempre vence o arquivo:

node --env-file=.env --env-file=.env.local index.js

Como carregar o .env no Python?#

Use o pacote python-dotenv:

pip install python-dotenv

import os
from dotenv import load_dotenv

load_dotenv()  # procura .env na pasta do script ou acima

token = os.environ["DISCORD_TOKEN"]  # KeyError se faltar
port = int(os.getenv("PORT", "3000"))
print(f"Subindo na porta {port}")

Por padrão load_dotenv() não substitui variáveis já existentes no ambiente; load_dotenv(override=True) faz o contrário. Se quiser só ler os valores sem alterar os.environ, use dotenv_values(".env"), que devolve um dicionário.

Em outros frameworks o arquivo pode ser lido sozinho. O Next.js carrega .env, .env.local e variantes por NODE_ENV, e só expõe ao navegador as variáveis com prefixo NEXT_PUBLIC_, que são gravadas no JavaScript no momento do build. No Docker Compose, a chave env_file do serviço carrega as variáveis do arquivo no ambiente do container.

Como não vazar segredos do .env?#

O risco real do .env é ele ir parar no repositório. Faça isto antes do primeiro commit:

1. Crie um .gitignore com a linha .env (e .env.* se usar variantes, liberando só .env.example).
2. Versione um .env.example com os nomes e valores falsos, para quem clonar saber o que preencher:

DISCORD_TOKEN=
DATABASE_URL=postgresql://usuario:senha@localhost:5432/meubanco
PORT=3000

3. Confira com git status que o .env não aparece como arquivo novo.
4. Nunca imprima valores em logs nem os coloque em prints de erro.

Se um segredo já foi commitado, apagar o arquivo não resolve, porque o histórico guarda o conteúdo. Gere uma chave nova e revogue a antiga. O passo a passo está em chave de API exposta no GitHub, e para bots vale ver o token do bot do Discord.

Quais erros são comuns com .env?#

A variável vem undefined. O arquivo não foi carregado (faltou --env-file ou load_dotenv()), está em outra pasta (o caminho do --env-file é relativo ao diretório atual, não ao script) ou o nome tem erro de digitação.

Mudei o valor e nada mudou. O processo lê o arquivo só ao iniciar: reinicie. Se a variável também existe no ambiente, ela vence o arquivo. Rode echo $DISCORD_TOKEN (ou $env:DISCORD_TOKEN no PowerShell) para ver.

O valor veio cortado no #. Coloque o valor entre aspas.

PORT não funciona como número. É texto. Converta com Number() ou int().

A variável do front-end aparece vazia. Em frameworks como o Next.js, só variáveis com prefixo NEXT_PUBLIC_ chegam ao navegador, e o valor é fixado no build. Nunca use esse prefixo para segredos.

Como fazer isso na Square Cloud#

Na Square Cloud, as variáveis de ambiente são configuradas por aplicação, no painel, pela API, pela CLI ou pela extensão do VS Code. O código continua lendo process.env ou os.environ normalmente.

Se você já tem um .env pronto, o painel importa o arquivo e preenche as variáveis. Também dá para exportar tudo de volta como KEY=VALUE. A mudança vale no próximo reinício da aplicação, sem rebuild. Dentro da aplicação, a variável SQUARECLOUD_APP_ID traz o ID dela em tempo de execução.

Assim o .env continua só no seu computador, listado no .gitignore, e os valores de produção ficam configurados na própria aplicação. Veja os detalhes em variáveis de ambiente na Square Cloud.