O que são variáveis de ambiente (e por que usar)

Toda aplicação precisa de valores que mudam conforme o lugar onde roda: o endereço do banco de dados, a porta, o token de um bot, a chave de uma API de pagamento. Escrever esses valores direto no código funciona no seu computador e vira problema no primeiro deploy.

Variáveis de ambiente resolvem isso. O código pergunta ao sistema "qual é o valor de DATABASE_URL?" e cada ambiente responde o seu. O código fica igual, a configuração muda. É um dos primeiros conceitos a dominar antes de qualquer deploy.

O que é uma variável de ambiente?#

É um par nome-valor que pertence ao ambiente de um processo. Quando o sistema operacional inicia um programa, entrega a ele uma cópia desse conjunto. O programa pode lê-la a qualquer momento, e os processos filhos que ele iniciar herdam a mesma cópia.

Você já usa algumas sem perceber: PATH diz onde o sistema procura executáveis e HOME aponta para a pasta do usuário. As suas são do mesmo tipo. No Linux/macOS, o primeiro exemplo define a variável só para aquele comando; no PowerShell, o segundo a mantém até você fechar o terminal:

PORT=3000 node index.js

$env:PORT = "3000"; node index.js

Duas regras valem para todas as linguagens. Primeiro, todo valor é texto: 3000 chega como "3000" e false chega como "false" (que, em muitas linguagens, é verdadeiro). Segundo, por convenção o nome não começa com número e usa MAIÚSCULAS e underscore, como API_KEY.

Como ler variáveis no código?#

No Node.js, elas ficam em process.env. No Python, em os.environ, que lança KeyError se a chave não existir; os.getenv devolve um valor padrão nesse caso.

// Node.js
const port = Number(process.env.PORT ?? 3000);
const token = process.env.DISCORD_TOKEN;
if (!token) {
  throw new Error("Defina DISCORD_TOKEN antes de iniciar");
}

import os

port = int(os.getenv("PORT", "8000"))
token = os.environ["DISCORD_TOKEN"]  # KeyError se não existir

Use valor padrão para o que é opcional (a porta) e falhe cedo para o que é obrigatório (o token). Um erro claro na inicialização custa menos que um undefined aparecendo em produção horas depois.

Por que não colocar a configuração no código?#

O guia 12-factor, uma referência clássica para apps na nuvem, define configuração como tudo que varia entre deploys: credenciais, endereços de serviços, nome de host. O teste que ele propõe: se você pudesse tornar o código público agora sem expor nenhuma credencial, a configuração está bem separada.

Há três ganhos práticos:

• Segurança. Um token no código vai para o Git, e o histórico guarda para sempre. Um token de bot do Discord ou uma chave de API que chega a um repositório público fica visível para qualquer pessoa: trate essa credencial como comprometida.
• Um código, vários ambientes. O mesmo build roda em desenvolvimento, teste e produção, trocando só as variáveis.
• Troca sem alterar o código. Rotacionar uma senha vira mudar um valor e reiniciar, sem novo commit.

O que é o arquivo .env e como usar?#

Definir dez variáveis na mão a cada execução cansa. O arquivo .env guarda um NOME=valor por linha e serve só para desenvolvimento:

DISCORD_TOKEN=cole_o_token_aqui
DATABASE_URL=postgres://usuario:senha@localhost:5432/app
PORT=3000

O Node.js lê esse formato sem biblioteca, com a flag --env-file:

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

Se a variável já existir no ambiente, ela vence o valor do arquivo. Em Python, o pacote python-dotenv faz o mesmo com load_dotenv().

O ponto crítico: coloque .env no .gitignore. Para quem clonar o projeto, versione um .env.example com os nomes e valores falsos: assim todos sabem o que configurar.

Como lidar com segredos?#

Variável de ambiente é melhor que valor escrito no código, mas não é cofre. Alguns cuidados:

1. Não imprima valores em logs nem em mensagens de erro.
2. Dê a cada serviço só as credenciais de que ele precisa.
3. Se um token vazou, revogue e gere outro. Apagar o commit não basta, pois o valor já pode ter sido copiado.
4. Nunca coloque segredos em variáveis lidas pelo navegador. Em frameworks de front-end, prefixos como NEXT_PUBLIC_ ou VITE_ expõem o valor no JavaScript enviado ao visitante: use-os só para dados públicos.

Quando variável de ambiente não é a melhor opção?#

Para configuração estrutural e longa, como listas de regras ou textos, um arquivo de configuração versionado é mais legível. Para segredos que mudam o tempo todo ou exigem auditoria de acesso, um cofre de segredos dedicado faz mais sentido. Para a imensa maioria dos bots e das APIs, porém, variáveis de ambiente bastam.

Como fazer isso na Square Cloud#

Na Square Cloud, o .env que você usa em desenvolvimento vira a configuração de produção sem copiar valor por valor: o painel importa o arquivo e cria as variáveis da aplicação, e exporta tudo de volta no formato KEY=VALUE quando você precisar. Cada variável também pode ser definida pela CLI (app env set KEY=VALUE), pela API ou pela extensão do VS Code.

Dois detalhes seguem as regras deste guia. Cada aplicação tem o próprio conjunto de variáveis e não lê as de outra, mesmo na mesma conta, então o bot nunca enxerga as credenciais da API. E uma mudança vale no próximo reinício, sem reenviar o código: rotacionar uma senha é trocar o valor e reiniciar. As variáveis já existem durante a instalação das dependências, e SQUARECLOUD_APP_ID entrega o ID da própria aplicação em runtime.

Veja o passo a passo na página de variáveis de ambiente e os comandos da CLI.