O Que São Variáveis de Ambiente e Segredos? Guia Simples

Uma variável de ambiente é uma definição com nome — como DATABASE_URL ou STRIPE_SECRET_KEY — que é entregue à sua app quando esta corre, em vez de ser escrita no código. Um segredo é uma variável de ambiente cujo valor tem de permanecer privado: uma chave de API, uma palavra-passe, uma chave de assinatura. Manter estes valores fora do código permite alterá-los sem editar a app, usar valores diferentes para testes e para clientes reais, e evitar que sejam divulgados quando partilha ou publica o seu código.

Porque é que importa quando cria com IA

No momento em que a sua app faz algo útil com outro serviço — aceita um pagamento, envia um email, chama um modelo de IA — precisa de uma chave. Os construtores de apps com IA pedem estas chaves regularmente, e o sítio onde a chave acaba decide se a sua app está segura.

Duas coisas correm mal com frequência em apps criadas com IA:

• A chave é colada no chat ou no código. Fica então no histórico do chat, nos ficheiros do projeto e em qualquer exportação ou repositório. Quem a vir pode usar a sua conta.
• A chave é usada no navegador. Se o código que chama a Stripe ou a OpenAI corre na página, a chave é enviada a cada visitante. As pessoas de facto olham, e os analisadores automáticos procuram chaves expostas constantemente.

Perceber as variáveis de ambiente permite-lhe detetar ambos os problemas e pedir a correção.

Uma analogia do dia a dia: o cofre do hotel

O código da sua app é como o quarto de hotel. Os hóspedes (e as empregadas, e qualquer pessoa a quem dê o cartão de acesso) passam por lá. Não deixaria o seu passaporte em cima da secretária.

As variáveis de ambiente são o cofre do quarto. O quarto sabe que existe um cofre e como o abrir quando é preciso, mas o passaporte não está à vista. E se mudar para outro quarto — da sua configuração de testes para o site em direto —, coloca um passaporte diferente no cofre desse quarto, sem redecorar nada.

Como funciona

O seu código refere um nome, não um valor. Em JavaScript num servidor, isso tem o aspeto de process.env.STRIPE_SECRET_KEY. Quando a app arranca, a plataforma onde corre preenche o valor desse nome. Altere o valor nas definições da plataforma, reinicie ou volte a publicar, e a app passa a usar o novo — sem alterar código.

De onde vêm os valores depende de onde a app corre:

Variáveis públicas vs secretas

Nem toda a variável de ambiente é secreta. Ajuda separá-las em dois grupos:

As frameworks web tornam esta separação explícita. No Vite, só as variáveis cujos nomes começam por VITE_ são incluídas no código do navegador; no Next.js, o prefixo é NEXT_PUBLIC_. Isto é uma funcionalidade de segurança: tudo o que tem esses prefixos acaba nos ficheiros que cada visitante descarrega, por isso um segredo nunca deve receber um deles.

Um exemplo prático: um botão de resumo com IA

Quer um botão "Resumir esta nota" que chama um modelo de IA.

A versão insegura: o código do botão, a correr no navegador, chama diretamente o fornecedor de IA com a chave de API escrita dentro dele. Funciona na pré-visualização. Mas significa também que qualquer pessoa pode abrir as ferramentas de programador do navegador, copiar a chave e gerar uma fatura na sua conta.

A versão segura:

1. Cria a chave no fornecedor de IA e guarda-a como segredo chamado OPENAI_API_KEY (ou semelhante) nas definições do seu projeto.
2. O backend tem uma rota, POST /api/summarise, que lê process.env.OPENAI_API_KEY, verifica se o utilizador tem sessão iniciada e chama o fornecedor.
3. O botão chama a sua rota, não o fornecedor. O navegador nunca vê a chave.
4. Acrescenta o mesmo segredo às definições da app publicada e volta a publicar, para que o site em direto também o tenha.

Esse padrão — o navegador chama o seu servidor, e o seu servidor guarda a chave e chama o serviço — aplica-se a pagamentos, email, mapas e a todas as outras APIs pagas. O guia para usar APIs de LLM aprofunda o caso da IA.

Termos-chave

• Ficheiro .env: um ficheiro de texto com linhas NOME=valor, usado no desenvolvimento local. Inclua-o no .gitignore para não ser enviado para o git.
• .env.example: uma cópia só com os nomes e sem valores reais, enviada para o repositório para que os outros saibam que variáveis definir.
• Rodar (rotate): substituir um segredo por um novo e revogar o antigo.
• Âmbito / permissões: muitos fornecedores permitem criar chaves que só podem fazer certas coisas. Uma chave que só envia emails é menos perigosa do que uma que pode fazer tudo.
• Chaves de teste vs reais: fornecedores como a Stripe dão-lhe chaves separadas para testes e para dinheiro real. Use chaves de teste até lançar.
• Segredo de assinatura: um segredo usado para verificar que uma mensagem, como um webhook, realmente veio do remetente.

Erros comuns e equívocos

• "O meu repositório é privado, por isso as chaves lá dentro estão bem." Os repositórios privados são partilhados, copiados (fork), exportados e clonados para portáteis. As chaves continuam a não pertencer lá. Se ligar um projeto ao GitHub, confirme que nenhum ficheiro .env está incluído.
• "Apaguei-a, por isso já não existe." O git guarda o histórico, e os registos do chat guardam as mensagens. Se uma chave foi alguma vez exposta, substitua-a.
• Usar um prefixo público num segredo. VITE_OPENAI_KEY coloca a sua chave no bundle do navegador.
• Esquecer de voltar a publicar. Alterar uma variável nas definições normalmente só tem efeito depois de a app reiniciar ou ser publicada de novo.
• Uma chave para tudo. Chaves separadas para teste e produção, e por app, permitem revogar uma sem partir as restantes.
• Sem limite de gastos. Para APIs pagas, defina um orçamento ou limite no painel do fornecedor, caso uma chave seja exposta.

O que pedir ao seu construtor de IA

• "Leia a chave secreta da Stripe a partir de uma variável de ambiente chamada STRIPE_SECRET_KEY. Use-a apenas no servidor."
• "Garanta que nenhum segredo é usado no código do cliente nem recebe um prefixo VITE_ / NEXT_PUBLIC_."
• "Crie um .env.example com todas as variáveis de que a app precisa, sem valores, e garanta que o .env está ignorado pelo git."
• "Verifique os ficheiros do frontend compilados à procura de qualquer texto que pareça uma chave de API."

A nossa lista de verificação de segurança para apps criadas com IA cobre os segredos juntamente com as outras verificações a fazer antes de lançar.

Segredos na Mythex

Na Mythex, os segredos são variáveis de ambiente do projeto que são injetadas tanto na sandbox de pré-visualização como na sua app publicada. Adiciona-os em definições do projeto → Segredos ou com /secrets no chat, e quando o agente precisa de uma chave mostra um cartão de segredos no chat, para que o valor vá para um campo de formulário e não para a transcrição da conversa. Se alterar um segredo de uma app em direto, volte a publicar para que a implementação o aplique. As exportações do projeto deixam os segredos de fora, e os ficheiros .env importados são limpos, para que os volte a adicionar nas definições. Veja variáveis de ambiente e segredos e segredos no chat na documentação.

Perguntas