Variáveis de Ambiente no Vite e Netlify: Guia Completo

Variáveis de Ambiente no Vite e Netlify: Guia Completo

Variáveis de ambiente no Vite são valores de configuração (como URLs de API e chaves públicas) lidos a partir de arquivos .env e acessados no código com import.meta.env. Só as variáveis com prefixo VITE_ chegam ao navegador, e no Netlify você precisa cadastrá-las no painel do site e refazer o deploy para que entrem no build. Neste guia você vê como configurar tudo corretamente e o que nunca colocar no front-end.

Como funcionam as variáveis de ambiente no Vite

O Vite carrega arquivos .env da raiz do projeto e expõe ao código do cliente apenas as variáveis que começam com VITE_. Segundo a documentação oficial do Vite, isso existe justamente para evitar que segredos sejam vazados sem querer para o bundle.

Os arquivos mais usados são:

• .env: valores carregados em todos os modos.
• .env.local: valores locais, ignorados pelo Git.
• .env.development e .env.production: valores específicos de cada modo.

No código, o acesso é feito assim:

const apiUrl = import.meta.env.VITE_API_URL

O Vite também disponibiliza variáveis embutidas como import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD e import.meta.env.BASE_URL, úteis para condicionar comportamentos entre desenvolvimento e produção.

Um ponto que confunde muita gente

As variáveis VITE_ são substituídas no momento do build. Ou seja, elas ficam gravadas no JavaScript final. Qualquer pessoa que abrir o DevTools consegue ler esses valores. Por isso, o prefixo VITE_ é para dados que podem ser públicos.

Como configurar variáveis de ambiente no Netlify

O arquivo .env.local não deve ser enviado ao repositório, então o Netlify não o enxerga. Você precisa cadastrar as variáveis na plataforma:

1. Abra o site no painel do Netlify.
2. Vá em Site configuration e depois em Environment variables.
3. Clique em adicionar variável e informe a chave (por exemplo, VITE_SUPABASE_URL) e o valor.
4. Salve e dispare um novo deploy.

Esse último passo é essencial: como o Vite grava os valores durante o build, alterar a variável no painel não muda um site já publicado. É preciso gerar um novo build. Também é possível gerenciar variáveis pelo Netlify CLI ou pelo arquivo netlify.toml, mas valores sensíveis são melhor mantidos no painel, fora do código versionado.

O Netlify permite ainda definir escopos, para que uma variável fique disponível apenas no build, nas funções ou em contextos de deploy específicos. Isso ajuda a separar produção de preview.

O que pode e o que não pode ir no front-end

A regra prática para quem trabalha com React, Vite e Supabase é simples:

• Pode usar com VITE_: URL do projeto Supabase, chave anon (pública por design e protegida por Row Level Security), chave pública de analytics e IDs de serviços públicos.
• Nunca use com VITE_: chave service_role do Supabase, chaves secretas de pagamento, tokens de APIs privadas e senhas de banco.

Para segredos, mantenha o valor sem o prefixo VITE_ e use-o apenas em Netlify Functions ou Edge Functions, que executam no servidor. O front-end chama a função, e a função usa o segredo. O Netlify também possui varredura de segredos no build, que alerta quando um valor sensível aparece no código publicado, mas ela é uma rede de proteção, não substitui o cuidado na configuração.

Erros comuns e como resolver

• Variável retorna undefined: confira se o nome começa com VITE_ e se você reiniciou o servidor de desenvolvimento após editar o .env.
• Funciona local e falha no Netlify: a variável não foi cadastrada no painel ou o deploy não foi refeito depois de cadastrar.
• Valor antigo em produção: limpe o cache e faça um novo deploy.
• .env enviado ao GitHub: adicione .env*.local ao .gitignore e troque as chaves expostas imediatamente.

Perguntas Frequentes

Por que minha variável de ambiente no Vite aparece como undefined? Normalmente porque o nome não começa com VITE_ ou porque o servidor não foi reiniciado após alterar o .env. No Netlify, também pode ser que ela não tenha sido cadastrada no painel.

Posso colocar a chave do Supabase em uma variável VITE_? A URL do projeto e a chave anon podem, desde que o Row Level Security esteja ativo nas tabelas. A chave service_role jamais deve ser exposta no front-end.

Preciso fazer novo deploy depois de mudar uma variável no Netlify? Sim. O Vite incorpora os valores durante o build, então a alteração só vale após um novo deploy.

Variáveis VITE_ são seguras para guardar segredos? Não. Elas ficam visíveis no JavaScript entregue ao navegador. Segredos devem ficar em funções de servidor.

Qual a diferença entre .env e .env.local no Vite? O .env vale para todos os modos e costuma ser versionado com valores não sensíveis, enquanto o .env.local guarda valores só da sua máquina e deve ficar fora do Git.

Conclusão

Configurar variáveis de ambiente no Vite e no Netlify se resume a três hábitos: usar VITE_ apenas para dados públicos, cadastrar tudo no painel do Netlify e refazer o deploy a cada mudança. Segredos ficam sempre no servidor. Na Stormcore, aplicamos essas práticas ao criar sites, sistemas e automações com React, Supabase e Netlify, para que cada projeto nasça seguro e fácil de manter.