# Vercel: variáveis de ambiente sem .env no Git
> Variáveis de ambiente, Development/Preview/Production, uma nova implementação e verificação segura de chaves no Next.js sem enviar segredos para o browser.
Source: https://ailoot.ai/blog/pt-pt/vercel-environment-variables/
Canonical: https://ailoot.ai/blog/pt-pt/vercel-environment-variables/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-229
Revision: sha256-c5b7c08e848145f015df4817818d07bd2014c4d370d7d094c41e9e8c4962a4b8
Principal conclusão
Se o ficheiro `.env` que contém os seus segredos não estiver no Git, adicione as variáveis necessárias à secção **Environment Variables** do seu projeto Vercel. Selecione o ambiente, guarde as definições e crie uma nova implementação: as versões já implementadas não serão alteradas. No Next.js, não adicione o prefixo `NEXT_PUBLIC_` a uma chave secreta: o respetivo valor será incluído no código do browser durante a compilação.
Este guia destina-se a um projeto já alojado no Vercel. Precisa de acesso às respetivas definições e de saber que variáveis a aplicação lê. O exemplo abaixo aplica-se ao Next.js; os nomes de variáveis de outra framework não podem ser transpostos automaticamente. O guia baseia-se na documentação oficial; não foi testado numa conta real.
[Na documentação, encontra informações práticas sobre a utilização do Ailoot](https://ailoot.ai/docs/).
## Porque não precisa de adicionar .env ao Git
Uma variável de ambiente é uma definição com um nome e um valor que uma aplicação recebe separadamente do seu código-fonte. Por exemplo, o nome `SERVICE_API_KEY` permite ao programa aceder ao valor da chave de um serviço externo. Não inclua a própria chave no guia, na sua conversa com um agente nem no repositório.
O Next.js pode carregar variáveis de ficheiros locais `.env*`. No entanto, um ficheiro local e as definições do projeto no Vercel são dois locais distintos. Se o ficheiro não for enviado para o repositório, defina os valores separadamente na plataforma de alojamento. O modelo padrão `create-next-app` adiciona ficheiros `.env` ao `.gitignore`; a documentação do Next.js avisa que quase nunca os deve enviar para o repositório.
Se ainda não tiver a certeza do que pode ser guardado nos ficheiros de código-fonte, comece pela [verificação de segurança de um projeto criado com IA](https://ailoot.ai/blog/pt-pt/vibe-coding-security/). Aqui, abordamos uma questão mais específica: onde definir a configuração de uma implementação concreta no Vercel.
## Primeiro, determine onde a aplicação lê a variável
Antes de introduzir quaisquer valores, faça uma lista dos **nomes**, sem os próprios segredos. Para cada nome, tem de determinar três aspetos: que ambiente o utiliza, onde é executado o código que lê a variável e quando é necessário o valor.
| O que verificar | Opções possíveis | Porque é importante |
|----|----|----|
| Ambiente do Vercel | Development, Preview, Production | A definição tem de se aplicar à versão que está a verificar |
| Onde é lida | Servidor ou browser | Uma chave privada não pode ser incluída no código do lado do cliente |
| Quando é lida | Durante a compilação ou durante a execução da função de servidor | No Next.js, os valores públicos ficam fixos durante a compilação |
O ambiente **Development** destina-se ao desenvolvimento local. **Preview** destina-se a implementações de pré-visualização e **Production** à versão principal publicada. O Preview pode ter definições para uma ramificação específica do Git: estas substituem as definições gerais do Preview com os mesmos nomes.
Num projeto Next.js, as variáveis sem `NEXT_PUBLIC_` estão disponíveis no servidor por predefinição. O prefixo `NEXT_PUBLIC_` permite incorporar o valor no JavaScript enviado para o browser. É adequado para uma definição explicitamente pública, como um rótulo de versão não secreto, mas não para uma chave API privada. Mesmo sem este prefixo, o código da aplicação não pode devolver manualmente um segredo ao cliente.
Se ainda não identificou a framework, peça ao agente para a identificar a partir dos ficheiros do projeto. A [comparação entre Astro e Next.js](https://ailoot.ai/blog/pt-pt/astro-vs-nextjs-for-ai-built-sites/) pode ajudar a compreender as diferenças; não pode aplicar a regra `NEXT_PUBLIC_` a todas as aplicações React.
A configuração do alojamento é uma das tarefas envolvidas no trabalho numa aplicação com um agente de IA.
## Como adicionar uma variável a um projeto Vercel
Siga pessoalmente os passos no painel oficial. Não dê uma chave real ao agente para a preencher no formulário e não anexe uma captura de ecrã que mostre o respetivo valor.
1. Abra o painel do Vercel e selecione o **projeto correto**. Não confie apenas na correspondência do nome do repositório: confirme que está a configurar a aplicação que pretende abrir.
2. Nas definições do projeto, aceda a **Environment Variables** na barra lateral.
3. Em **Name**, introduza o nome que a aplicação lê, como `SERVICE_API_KEY`. Este é um nome de exemplo; se o código esperar outro, utilize exatamente a grafia correspondente.
4. Em **Value**, introduza o valor do seu gestor de credenciais. Não o inclua no código-fonte, numa conversa nem num registo de verificação.
5. Selecione o ambiente que necessita desta definição. Utilize **Preview** para verificar uma versão de pré-visualização e **Production** para a versão principal. Não atribua automaticamente o mesmo segredo a todos os ambientes.
6. Se a definição Preview se aplicar a uma ramificação específica, confirme a ramificação selecionada e qualquer substituição com o mesmo nome.
7. Clique em **Save**.
O Vercel disponibiliza as variáveis do projeto durante a compilação e quando as Vercel Functions do lado do servidor são executadas. No entanto, o facto de um valor estar disponível no Vercel não significa que possa ser enviado para o browser: isso depende do código da aplicação e das regras da framework.
## Porque precisa de uma nova implementação depois de clicar em Save
Guardar uma variável não altera as implementações existentes. A documentação do Vercel exige que volte a implementar o projeto para que a nova definição chegue à versão que utiliza.
Ao trabalhar através do Git, pode criar uma nova implementação Production enviando um commit para a ramificação indicada em **Production Branch**, e uma implementação Preview enviando um commit para outra ramificação. Não presuma que a ramificação principal se chama sempre `main`: confirme a definição do seu projeto. Esta deve ser uma publicação normal e acordada do projeto, sem adicionar um ficheiro secreto ao commit.
Depois de iniciar a implementação, aguarde até a compilação terminar e abra o URL da **nova** implementação. Registe o URL, o ambiente e a ramificação. Se verificar o URL antigo de uma implementação individual, as novas definições não estarão disponíveis.
O Next.js tem outra condição: referências como `process.env.NEXT_PUBLIC_RELEASE_LABEL` são substituídas pelos respetivos valores durante `next build`. O valor fica fixo após a compilação. Alterar a definição sem uma nova compilação não atualizará o JavaScript do lado do cliente que já foi enviado.
## Como verificar o resultado sem expor a chave
Comece com um exemplo seguro: um rótulo explicitamente não secreto, com o nome `NEXT_PUBLIC_RELEASE_LABEL` e o valor `preview-check`. São um nome e um texto de exemplo, não uma chave nem um teste aqui realizado. Se uma aplicação Next.js ler esta variável diretamente através de `process.env.NEXT_PUBLIC_RELEASE_LABEL`, pode apresentar o rótulo no local previsto da interface depois de uma nova compilação. Esta verificação apenas confirma que a definição pública foi transmitida.
**Uma chave privada é verificada de outra forma.** Não apresente o respetivo valor, uma parte dele, o seu comprimento ou todo o objeto `process.env`. Não crie um URL público que devolva o conteúdo da variável. Primeiro, verifique apenas se a definição está «presente / ausente» no servidor; em seguida, verifique separadamente a função da aplicação que utiliza o serviço. A presença de uma definição não prova que a chave seja válida ou tenha as permissões necessárias.
Pode registar os resultados sem segredos:
- o projeto, o ambiente e a ramificação correspondem aos selecionados durante a configuração;
- está a verificar o URL de uma nova implementação criada depois de guardar a variável;
- a compilação terminou e a função necessária da aplicação foi executada com dados de teste seguros;
- o segredo não é exposto no browser, nas respostas da API, nos registos ou nas conversas.
Se a função efetuar um pagamento, enviar uma mensagem ou executar outra ação com consequências, utilize o modo de teste indicado pelo serviço. Verificar a configuração não autoriza, por si só, uma operação real.
## O que verificar se o valor continuar undefined
`undefined` significa que não foi obtido nenhum valor naquele ponto de acesso. Verifique o nome, o ambiente e a versão por esta ordem, sem alterar todas as definições ao mesmo tempo.
| Sintoma | O que verificar |
|----|----|
| Funciona localmente, mas não em Preview | Se o nome existe nas definições Preview do projeto; se está selecionada outra ramificação |
| Preview funciona, mas Production não | Se o nome está definido para Production; se foi criada uma nova versão principal depois de clicar em Save |
| Uma ramificação Preview comporta-se de forma diferente | Se existe um valor com o mesmo nome definido para essa ramificação e que substitui a definição geral |
| O servidor vê a variável, mas o browser não | No Next.js, é o comportamento esperado para uma variável não pública; não transfira uma chave privada para o browser |
| O rótulo público do Next.js continua com o valor antigo | Se foi feita uma nova compilação com o valor necessário; se o URL aberto pertence a essa implementação |
| O nome público está correto, mas a substituição não funciona | Se o código a lê dinamicamente com `process.env[varName]`: o Next.js não incorpora estas referências no código |
Depois de verificar o nome, o ambiente e a nova versão, um erro na função continua sem provar que a variável o causou. Investigue o erro específico do código do lado do servidor sem publicar dados de diagnóstico que contenham segredos. Este guia não promete resolver todas as respostas HTTP 500.
A mudança para o seu próprio servidor exige outro procedimento: consulte o [guia de implementação de um projeto com Coolify](https://ailoot.ai/blog/pt-pt/coolify-claude-code-deploy/). Os nomes dos botões e os passos de configuração do Vercel não se aplicam a esse caso.
### Fontes
- [Variáveis de ambiente do Vercel](https://vercel.com/docs/environment-variables)
- [Adicionar e gerir variáveis de ambiente do Vercel](https://vercel.com/docs/environment-variables/managing-environment-variables)
- [Variáveis de ambiente do Next.js](https://nextjs.org/docs/app/guides/environment-variables)
[Ir para Ailoot](https://ailoot.ai/).
## Perguntas frequentes
### Porque continua a variável undefined depois de a guardar na Vercel?
Verifique projeto, ambiente e eventual âmbito por branch e crie uma implementação nova. As implementações existentes não recebem uma variável só porque guardou uma definição nova.
### Posso acrescentar NEXT_PUBLIC_ para tornar um segredo visível à aplicação Next.js?
Não use esse prefixo num segredo: inclui o valor no código do navegador durante a compilação. Mantenha-o no servidor e verifique a presença sem apresentar a chave.
## Ailoot · A empresa e a sua carteira de projetos
A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.
A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.
A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.