Uma variável de ambiente é um par de nome e valor que existe no sistema onde o programa executa. O código lê esse valor na hora de rodar. Assim, dados que mudam de um ambiente para outro ficam separados do código.

Como funciona

Quando você abre um terminal ou inicia um servidor, o sistema operacional entrega ao programa um conjunto de variáveis. O programa consulta pelo nome e recebe o valor.

O mesmo código pode rodar no seu computador, em um servidor de testes e em produção. O que muda é só o valor de cada variável: o banco de dados de teste e o de produção, por exemplo.

Em Node.js, a leitura é assim:

JavaScript · app.js
const chave = process.env.OPENAI_API_KEY;
if (!chave) throw new Error("Faltou a variável OPENAI_API_KEY");

Para definir uma variável no terminal:

export MINHA_CHAVE="valor-secreto"

Essas definições valem para a sessão atual. Para algo permanente, usa-se o painel da hospedagem, o arquivo .env ou a configuração do sistema.

Exemplo prático

Você criou um script que chama uma API de IA. Se escrever a chave direto no código e subir o projeto para o GitHub, qualquer pessoa pode ver e usar essa chave, e a conta sai cara.

O jeito certo é guardar a chave numa variável de ambiente e ler no código. No repositório fica só o nome da variável, nunca o valor. Em um arquivo de exemplo, você lista os nomes esperados para que outras pessoas saibam o que configurar.

Outro caso comum: o endereço da API muda entre teste e produção. Com uma variável como API_URL, você troca o destino sem mexer em nenhuma linha de código.

Para que serve

Serve principalmente para proteger segredos, como chaves de API, senhas e tokens. Também serve para configurar o comportamento do app em cada ambiente, ligar ou desligar recursos e definir portas e endereços.

Plataformas de hospedagem e ferramentas de agentes de código usam variáveis de ambiente para receber as chaves dos provedores de modelos. Em geral, é o único lugar onde esses valores deveriam ficar.

Cuidados importantes

  • Nunca envie arquivos com segredos para o repositório. Coloque o .env no .gitignore.
  • Não imprima variáveis sensíveis em logs.
  • Se uma chave vazar, gere outra e revogue a antiga imediatamente.
  • Variáveis são texto puro no processo. Para segredos muito críticos, considere um gerenciador de segredos.

Seguindo esses pontos, você mantém o projeto limpo, portável e bem mais seguro.