Frontend Academy · Aula

Variáveis de ambiente na integração contínua

Armazenar segredos no GitHub Secrets, injetá-los na compilação como variáveis de ambiente e aceder-lhes no Vite com import.meta.env ou no Next.js com process.env.

Variáveis de ambiente na integração contínua é uma aula grátis de Frontend Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Frontend Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Frontend Academy inclui 4 aulas no total.

Por que ambientes diferentes?

Os aplicativos precisam de valores diferentes em cada ambiente: URL da API de desenvolvimento, URL da API de homologação e URL da API de produção. Além disso, há segredos (chaves de API e tokens) que nunca devem chegar ao repositório. As variáveis de ambiente são a maneira padrão de injetar esses valores.

Públicas versus exclusivas do servidor

As variáveis de front-end incorporadas ao pacote são públicas — qualquer pessoa com o DevTools pode visualizá-las. Nunca coloque segredos nelas. As variáveis do lado do servidor (usadas em funções sem servidor, SSR e rotas de API) podem ser verdadeiros segredos.

Variáveis de ambiente do Vite

O Vite expõe ao código do cliente as variáveis com o prefixo VITE_ por meio de import.meta.env.

# .env
VITE_API_URL=https://api.example.com
VITE_FEATURE_FLAGS={"newOnboarding":true}

# In code:
const apiUrl = import.meta.env.VITE_API_URL;

# DEV_ONLY or NEVER PREFIXED vars are NOT exposed:
SECRET_KEY=xxx  # not accessible to client code

Variáveis de ambiente do Next.js

O Next usa o prefixo NEXT_PUBLIC_ nas variáveis públicas. As variáveis exclusivas do servidor não têm prefixo (são usadas em manipuladores de rotas e em getServerSideProps).

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com  # client-accessible
DATABASE_URL=postgres://...                  # server-only

# Client:
const url = process.env.NEXT_PUBLIC_API_URL;

# Server (API route):
const db = process.env.DATABASE_URL;

Arquivos .env locais

Use .env.local para substituições pessoais e .env.development / .env.production para padrões específicos de cada ambiente. Adicione .env.local ao .gitignore — nunca confirme segredos.

# .gitignore
.env.local
.env.*.local

# Commit only .env.example with placeholder values:
VITE_API_URL=https://api.example.com
DATABASE_URL=

Armazenando segredos no GitHub Actions

Adicione os segredos em Configurações do repositório → Segredos e variáveis → Actions. Acesse-os por meio de secrets.NAME.

# .github/workflows/deploy.yml
- name: Deploy
  env:
    VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  run: |
    npx vercel --token $VERCEL_TOKEN --prod
    npx sentry-cli releases new $RELEASE

Segredos específicos do ambiente

Os ambientes do GitHub (Configurações → Ambientes) permitem limitar os segredos a um ambiente específico (homologação ou produção), com etapas opcionais de aprovação.

# Job that requires environment:
deploy-prod:
  environment: production   # requires reviewer approval if configured
  steps:
    - run: deploy
      env:
        DB_URL: ${{ secrets.DB_URL }}  # only prod's DB_URL is exposed

Variáveis de ambiente do provedor de hospedagem

Vercel, Netlify e Cloudflare expõem variáveis de ambiente à compilação e à execução do seu aplicativo. Defina-as no painel ou pela CLI.

# Vercel:
vercel env add VITE_API_URL production
vercel env add VITE_API_URL preview

# Netlify:
netlify env:set VITE_API_URL https://api.example.com

# Cloudflare Pages:
wrangler pages secret put API_URL

Não codifique segredos diretamente nos pacotes de front-end

Se um valor estiver no seu JS do cliente, ele será público. As chaves de API para SDKs de terceiros (chave publicável do Stripe e chave de pesquisa do Algolia) foram projetadas para serem públicas. Qualquer outra chave de API do servidor deve permanecer no back-end.

Validando variáveis de ambiente durante a compilação

Use zod ou envalid para fazer as compilações falharem quando faltarem variáveis de ambiente obrigatórias.

// env.ts
import { z } from 'zod';

const envSchema = z.object({
  VITE_API_URL: z.string().url(),
  VITE_SENTRY_DSN: z.string().url().optional()
});

export const env = envSchema.parse(import.meta.env);
// Throws helpful error if VITE_API_URL is missing

Durante a compilação versus durante a execução

As variáveis de ambiente usadas durante a compilação são incorporadas ao pacote — alterá-las exige uma nova compilação. As variáveis usadas durante a execução (nas rotas de API do Next, nas funções da Netlify e nos Workers da Cloudflare) são avaliadas a cada solicitação. Escolha com base na necessidade de alterar o valor sem fazer uma nova implantação.

Rotação de segredos

Faça a rotação dos segredos regularmente (a cada 90 dias) e após qualquer mudança na equipe. Use o 1Password Secrets Automation, o AWS Secrets Manager ou uma solução semelhante para manter os segredos atualizados no CI sem atualizações manuais.

Armadilhas comuns

1) Confirmar um .env com segredos reais — use git-secrets para evitar isso. 2) Expor variáveis do servidor ao cliente (prefixo incorreto). 3) Esquecer de definir variáveis de ambiente nas implantações de pré-visualização. 4) Misturar chaves de teste e de produção no mesmo ambiente.

Verificação rápida

Por que as variáveis de ambiente do Vite expostas ao cliente devem ter o prefixo VITE_?

Recapitulação: variáveis de ambiente no CI

Variáveis públicas: têm prefixo (VITE_, NEXT_PUBLIC_), são incorporadas ao pacote e ficam visíveis para os usuários. Variáveis exclusivas do servidor: não têm prefixo e são usadas em rotas de API ou SSR. .env.local fica no .gitignore; confirme .env.example. Use os segredos do GitHub para o CI e os ambientes do GitHub para limitar o acesso à produção. Os provedores de hospedagem (Vercel, Netlify e Cloudflare) definem variáveis por ambiente. Valide-as com zod durante a compilação.

Perguntas Frequentes

A aula “Variáveis de ambiente na integração contínua” é grátis?

Sim — o texto completo de “Variáveis de ambiente na integração contínua” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Frontend Academy, atualize para CoddyKit PRO. O curso de Frontend Academy inclui 4 aulas no total.

O que vou aprender em “Variáveis de ambiente na integração contínua”?

Armazenar segredos no GitHub Secrets, injetá-los na compilação como variáveis de ambiente e aceder-lhes no Vite com import.meta.env ou no Next.js com process.env. Você pratica Frontend Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Frontend Academy?

Nenhuma experiência prévia é necessária. Frontend Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Variáveis de ambiente na integração contínua”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Frontend Academy?

Sim. Cada aula de Frontend Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

GitHub Actions para frontend: lint, testes e compilação
Implementação no Vercel, Netlify e Cloudflare Pages
Variáveis de ambiente na integração contínua
Verificações automatizadas do Lighthouse

← Voltar para Frontend Academy