Vercel: variáveis de ambiente sem .env no Git

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.

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. 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 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 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.

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. Os nomes dos botões e os passos de configuração do Vercel não se aplicam a esse caso.

Ir para Ailoot.