Variáveis de ambiente

Variáveis de ambiente guardam configuração e segredos fora do código: URLs de banco, chaves de APIs externas, flags de comportamento e qualquer valor que mude entre ambientes. A aplicação lê esses valores em tempo de execução, por exemplo com process.env.DATABASE_URL no Node.js ou os.environ["DATABASE_URL"] no Python.

Onde configurar

Para apenas visualizar valores, use project.env.read. Valores podem ser sensíveis: conceda leitura somente a quem realmente precisa.

Limites

Arquivos grandes, certificados extensos ou listas volumosas não devem ser guardados em variáveis. Prefira gerar esses dados no build, guardá-los no armazenamento persistente ou buscá-los de um serviço próprio.

O que acontece ao alterar

• Salvar alterações em variáveis reinicia as instâncias do projeto para que os novos valores sejam carregados.
• Em projetos com mais de uma instância, planeje a alteração para um horário de menor uso e acompanhe os logs logo após salvar.
• Ambientes de preview herdam as variáveis do projeto principal a cada criação ou atualização do preview. Revise variáveis que apontam para bancos ou serviços compartilhados; veja Ambientes de Preview.

Variáveis durante o build

Em projetos com origem em um repositório GitHub, as variáveis do projeto também ficam disponíveis para o Comando Pré-build e o Comando Build. É assim que frameworks que embutem configuração no código enviado ao navegador recebem seus valores, como VITE_* no Vite e NEXT_PUBLIC_* no Next.js.

• Valores usados no build ficam gravados no resultado do build. Salvar uma alteração reinicia as instâncias, mas não refaz o build: para aplicar o novo valor, escolha Novo build em Logs de build ou publique um novo commit.
• Tudo o que o build embute no código do navegador fica visível para quem acessa a aplicação. Use VITE_*, NEXT_PUBLIC_* e prefixos equivalentes somente para valores públicos, como a URL de uma API, e nunca para senhas ou chaves privadas.
• As variáveis só são usadas em builds do repositório conectado ao projeto.

Variáveis definidas pela plataforma

A Zenifra injeta automaticamente:

Use essa variável para identificar a versão em logs, respostas de diagnóstico ou ferramentas de monitoramento. Não defina ZENIFRA_INSTANCE_VERSION manualmente: o valor é sempre substituído pela plataforma.

Conexão com bancos e serviços gerenciados

A DATABASE_URL não é injetada automaticamente em projetos HTTP. Copie os dados de conexão do banco ou do serviço gerenciado no console e cadastre a variável no projeto da aplicação:

DATABASE_URL=postgres://app:SENHA@HOST:PORTA/app
VALKEY_URL=valkeys://default:SENHA@HOST:PORTA/0

Ao rotacionar a senha de um banco, atualize as variáveis de todas as aplicações que o utilizam.

Boas práticas

• Nunca versione segredos no repositório nem os inclua em imagens OCI.
• Use nomes descritivos e em maiúsculas, como STRIPE_WEBHOOK_SECRET ou FEATURE_NEW_CHECKOUT.
• Separe valores de desenvolvimento local (arquivo .env fora do Git) dos valores de produção cadastrados no console.
• Revise quem tem project.env.read: essa permissão permite ler segredos em texto claro.
• Ao suspeitar de vazamento, gere uma nova credencial no serviço de origem, atualize a variável e revogue a antiga.

Próximos passos

• Configuração do projeto
• Armazenamento persistente
• Segurança
• Limites e quotas

FAQ

Preciso fazer um novo deploy depois de alterar uma variável?

Para variáveis lidas em tempo de execução, não: ao salvar, as instâncias são reiniciadas e passam a ler os novos valores. Para variáveis usadas no build, como VITE_* e NEXT_PUBLIC_*, sim: escolha Novo build em Logs de build para gerar a aplicação com o novo valor. Veja Variáveis durante o build.

Posso definir a porta por variável?

A porta da aplicação é configurada no próprio projeto. Se o seu código lê PORT, cadastre a variável com o mesmo valor configurado na porta do projeto.

As variáveis aparecem nos logs?

Não, a menos que a sua aplicação as imprima. Evite registrar valores de segredos.