Frontend Academy · Lezione

Variabili d’ambiente nella CI

Conservare i segreti in GitHub Secrets, iniettarli nella build come variabili d’ambiente e accedervi in Vite con import.meta.env o in Next.js con process.env

Variabili d’ambiente nella CI è una lezione Frontend Academy gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Frontend Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Frontend Academy include 4 lezioni in totale.

Perché ambienti diversi?

Le app hanno bisogno di valori diversi per ogni ambiente: URL dell'API di sviluppo, URL dell'API di staging e URL dell'API di produzione. Inoltre, ci sono segreti (chiavi API e token) che non devono mai finire nel repository. Le variabili d'ambiente sono il metodo standard per iniettare questi valori.

Pubbliche e solo server

Le variabili frontend integrate nel bundle sono pubbliche — visibili a chiunque utilizzi gli strumenti per sviluppatori. Non vi inserisca mai segreti. Le variabili lato server (usate nelle funzioni serverless, nel rendering SSR e nelle route API) possono essere veri segreti.

Variabili d'ambiente di Vite

Vite espone al codice client, tramite import.meta.env, le variabili con prefisso VITE_.

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

Variabili d'ambiente di Next.js

Next aggiunge il prefisso NEXT_PUBLIC_ alle variabili pubbliche. Le variabili riservate al server non hanno prefisso e vengono usate in Route Handlers e 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;

File .env locali

Usi .env.local per le personalizzazioni personali e .env.development / .env.production per i valori predefiniti specifici dell'ambiente. Aggiunga .env.local a .gitignore: non esegua mai il commit dei segreti.

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

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

Memorizzare i segreti in GitHub Actions

Aggiunga i segreti in Settings → Secrets and variables → Actions del repository. Vi acceda tramite 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

Segreti specifici per ambiente

Gli ambienti GitHub (Settings → Environments) consentono di limitare i segreti a un ambiente specifico (staging, produzione), con facoltativi passaggi di approvazione.

# 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

Variabili d'ambiente del provider di hosting

Vercel, Netlify e Cloudflare espongono tutti le variabili d'ambiente al build e al runtime. Le imposti nella dashboard o tramite 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

Non inserisca segreti nei bundle frontend

Se un valore si trova nel JavaScript client, è pubblico. Le chiavi API per gli SDK di terze parti (chiave pubblicabile di Stripe, chiave di ricerca di Algolia) sono progettate per essere pubbliche. Qualsiasi altra cosa, come le chiavi API del server, deve rimanere nel backend.

Convalidare le variabili d'ambiente durante il build

Usi zod o envalid per interrompere i build se mancano variabili d'ambiente obbligatorie.

// 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 il build e durante il runtime

Le variabili d'ambiente del build vengono integrate nel bundle: per modificarle è necessario eseguire nuovamente il build. Le variabili d'ambiente del runtime (route API di Next, Netlify Functions, Cloudflare Workers) vengono valutate a ogni richiesta. Scelga in base alla necessità di modificare il valore senza un nuovo deploy.

Rotazione dei segreti

Ruoti regolarmente i segreti (ogni 90 giorni) e dopo ogni cambiamento nel team. Usi 1Password Secrets Automation, AWS Secrets Manager o strumenti simili per mantenere aggiornati i segreti nella CI senza interventi manuali.

Problemi comuni

1) Eseguire il commit di .env con segreti reali: usi git-secrets per impedirlo. 2) Esporre le variabili server al client (prefisso errato). 3) Dimenticare di impostare le variabili d'ambiente nei deploy di anteprima. 4) Mescolare le chiavi di test e di produzione nello stesso ambiente.

Verifica rapida

Perché le variabili d'ambiente di Vite esposte al client devono avere il prefisso VITE_?

Riepilogo: variabili d'ambiente nella CI

Variabili pubbliche: hanno un prefisso (VITE_, NEXT_PUBLIC_), vengono integrate nel bundle e sono visibili agli utenti. Variabili riservate al server: non hanno prefisso e vengono usate nelle route API o nel rendering SSR. Inserisca .env.local in .gitignore e esegua il commit di .env.example. Usi GitHub Secrets per la CI e GitHub Environments per limitare l'accesso alla produzione. I provider di hosting (Vercel, Netlify, Cloudflare) impostano tutti le variabili per ambiente. Convalidi le variabili con zod durante il build.

Domande Frequenti

La lezione «Variabili d’ambiente nella CI» è gratuita?

Sì — il testo completo di «Variabili d’ambiente nella CI» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Frontend Academy, passa a CoddyKit PRO. Il corso Frontend Academy include 4 lezioni in totale.

Cosa imparerò in «Variabili d’ambiente nella CI»?

Conservare i segreti in GitHub Secrets, iniettarli nella build come variabili d’ambiente e accedervi in Vite con import.meta.env o in Next.js con process.env Eserciti Frontend Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Frontend Academy?

Non è richiesta alcuna esperienza precedente. Frontend Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «Variabili d’ambiente nella CI»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Frontend Academy?

Sì. Ogni lezione Frontend Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

GitHub Actions per il frontend: lint, test e build
Deploy su Vercel, Netlify e Cloudflare Pages
Variabili d’ambiente nella CI
Controlli Lighthouse automatizzati

← Torna a Frontend Academy