Variabili d'ambiente: cosa sono e perché online le chiavi mancano

Le variabili d'ambiente sono impostazioni che stanno fuori dal codice della tua app: l'indirizzo del database, le chiavi API dei servizi esterni, l'URL del sito. Se la tua app creata con l'AI funziona in anteprima ma online non si collega a nulla, o il tuo file .env sembra non funzionare dopo la pubblicazione, quasi sempre è perché quelle impostazioni non sono arrivate sul server, oppure ci sono arrivate nel momento sbagliato. Vediamo cosa sono, perché si perdono e come sistemarle senza mettere a rischio la sicurezza.

Cosa sono le variabili d'ambiente

Una variabile d'ambiente è una coppia nome-valore, per esempio:

VITE_SUPABASE_URL=https://abcdefgh.supabase.co

Il codice non contiene l'indirizzo vero e proprio: contiene solo il nome della variabile, e al momento giusto va a leggerne il valore. È come una ricetta che dice «aggiungi il sale» senza specificare la marca: chi cucina usa quello che trova in dispensa.

Questo sistema ha due vantaggi. Il primo è che la stessa app può usare valori diversi a seconda dell'ambiente: un database di prova durante lo sviluppo, quello vero in produzione, cioè nella versione online usata dagli utenti. Il secondo è che le informazioni sensibili restano fuori dal codice, e quindi fuori da GitHub e dagli occhi di chi lo legge.

Una chiave API, per chiarezza, è una specie di password che permette alla tua app di usare un servizio esterno: il database, i pagamenti, un modello di intelligenza artificiale, l'invio di email.

Il file .env e perché online non funziona

Durante lo sviluppo le variabili stanno spesso in un file chiamato .env, nella cartella principale del progetto. È un semplice file di testo, con una variabile per riga.

Il punto è che quel file, di solito, non viene pubblicato. È escluso apposta tramite .gitignore, l'elenco dei file da non caricare su GitHub, proprio perché contiene informazioni riservate. Quindi, quando l'hosting prende il codice da GitHub per fare la build, il .env non c'è. Le variabili vanno inserite a mano nel pannello dell'hosting, in una sezione che di solito si chiama «Environment variables» o simile.

Se pubblichi direttamente dalla piattaforma AI (Lovable, Bolt, Replit), spesso è lei a gestire le variabili, a volte in una sezione dedicata ai segreti. Ma se sposti l'app altrove, non ti seguono: Lovable, per esempio, specifica nella sua documentazione che i segreti configurati non vengono trasferiti a un hosting esterno e vanno reinseriti a mano.

Le cause più comuni delle chiavi che mancano in produzione

Le hai aggiunte, ma non hai rifatto il deploy

È la causa più frequente. Nelle app create con Vite, la base di molti progetti generati con l'AI, le variabili destinate al browser vengono scritte dentro i file al momento della build. Se aggiungi una variabile dopo, la versione online non la vede finché non rifai la build. Vercel lo dice esplicitamente nella sua documentazione: le modifiche alle variabili valgono solo per i nuovi deploy, non per quelli già pubblicati.

Il prefisso del nome è sbagliato

Per motivi di sicurezza, i framework rendono visibili al browser solo le variabili con un prefisso preciso: VITE_ per i progetti Vite, NEXT_PUBLIC_ per Next.js. Se nel codice c'è import.meta.env.VITE_SUPABASE_URL ma nel pannello hai scritto SUPABASE_URL, per l'app quella variabile non esiste.

Errori di battitura e spazi

Un nome scritto in modo leggermente diverso, uno spazio prima o dopo il valore, delle virgolette di troppo: per il computer sono variabili diverse o valori sbagliati. Copia e incolla i nomi direttamente dal codice, invece di riscriverli.

Ambiente sbagliato

Alcuni hosting distinguono tra più ambienti: produzione, anteprima (preview), sviluppo. Su Vercel, per esempio, ogni variabile può valere per uno o più di questi. Se l'hai impostata solo per l'anteprima, il sito di produzione non la riceve.

Come capire se il problema sono le variabili

Apri l'app online, premi F12 (oppure clic destro e «Ispeziona») e guarda la scheda Console. Alcuni segnali tipici:

• supabaseUrl is required.: l'app ha provato a collegarsi a Supabase senza conoscerne l'indirizzo.
• Invalid API key o 401 Unauthorized: la chiave c'è, ma è sbagliata, revocata o appartiene a un altro progetto.
• Nella scheda Rete, richieste verso indirizzi che contengono la parola undefined: il codice ha inserito nell'URL una variabile vuota.
• Funzioni che usano servizi esterni (email, AI, pagamenti) che online falliscono senza spiegazioni, mentre in anteprima funzionavano.

Se vedi uno di questi segnali solo sulla versione online, sei quasi certamente nel caso giusto. Per un quadro più ampio delle differenze tra anteprima e produzione, c'è la guida su cosa fare se l'app funziona in anteprima ma non online.

Chiavi pubbliche e chiavi segrete: la distinzione che conta

Qui c'è un punto di sicurezza che vale più di tutto il resto dell'articolo. Tutto ciò che ha il prefisso VITE_ o NEXT_PUBLIC_ finisce nei file che il browser scarica: chiunque, con un minimo di pratica, può leggerlo. La documentazione di Vite lo dice chiaramente: queste variabili non devono contenere informazioni sensibili.

Alcune chiavi sono fatte apposta per stare nel browser, altre no.

La chiave pubblica di Supabase, in particolare, è sicura solo se nel database sono attive le regole RLS (Row Level Security, cioè regole che stabiliscono chi può leggere e modificare ogni riga di una tabella). Senza, chiunque abbia quella chiave può accedere ai dati. Lo spieghiamo nella guida su Supabase RLS e dati esposti.

Se scopri che una chiave segreta è finita in una variabile pubblica, o direttamente nel codice, spostarla non basta: va revocata e sostituita con una nuova. Trovi i passaggi nell'articolo sulle chiavi API esposte nel frontend.

Come sistemare le variabili, passo per passo

1. Fai l'elenco delle variabili usate dall'app. Cerca nel codice import.meta.env (progetti Vite) o process.env (Next.js e codice lato server), oppure parti dal file .env dell'anteprima, se ce l'hai. Puoi anche chiedere all'AI: «Elencami tutte le variabili d'ambiente che usa il progetto e in quali file».
2. Separa pubbliche e segrete aiutandoti con la tabella qui sopra. Le segrete non devono avere prefissi pubblici.
3. Inseriscile nel pannello dell'hosting, con nomi identici a quelli del codice, nell'ambiente giusto (di solito produzione).
4. Rifai il deploy. Senza una nuova build, le modifiche non hanno effetto.
5. Verifica online in una finestra in incognito, con la console aperta.
6. Proteggi i valori. Non incollare chiavi segrete in chat, email o screenshot. Quando chiedi aiuto, anche all'AI, mostra i nomi delle variabili, non i valori.

Quando conviene farti aiutare

Se dopo aver ricontrollato nomi, prefissi e deploy le chiavi continuano a mancare, o se non sei sicuro di quali chiavi siano segrete e dove siano finite, conviene fermarsi e fare un controllo completo. Una variabile mancante blocca l'app; una chiave segreta esposta può costarti molto di più, in soldi e in dati.

Possiamo fare questo controllo insieme: verifichiamo quali variabili usa la tua app, dove sono configurate e se qualcuna è esposta. Prenota una call gratuita di 20 minuti.