Vercel: variabili d'ambiente senza .env in Git

Questa guida è rivolta a un progetto già ospitato su Vercel. Ti servono l'accesso alle sue impostazioni e la conoscenza delle variabili lette dall'applicazione. L'esempio seguente si applica a Next.js; i nomi delle variabili di un altro framework non possono essere trasferiti automaticamente. La guida si basa sulla documentazione ufficiale; non è stata testata su un account reale.

Le informazioni pratiche sull'uso di Ailoot sono disponibili nella documentazione.

Perché non è necessario aggiungere .env a Git#

Una variabile d'ambiente è un'impostazione con un nome e un valore che un'applicazione riceve separatamente dal codice sorgente. Per esempio, il nome SERVICE_API_KEY consente al programma di accedere al valore della chiave di un servizio esterno. Non inserire la chiave stessa nella guida, nella conversazione con un agente o nel repository.

Next.js può caricare variabili da file .env* locali. Tuttavia, un file locale e le impostazioni di un progetto in Vercel sono due posizioni distinte. Se il file non viene inviato al repository, imposta i valori separatamente sulla piattaforma di hosting. Il modello standard create-next-app aggiunge i file .env a .gitignore; la documentazione di Next.js avverte che quasi mai dovresti inviarli al repository.

Se non hai ancora chiaro cosa può essere memorizzato nei file sorgente, inizia dal controllo di sicurezza per un progetto realizzato con l'IA. Qui affrontiamo una domanda più specifica: dove impostare la configurazione per un determinato deployment Vercel.

Per prima cosa, determina dove l'applicazione legge la variabile#

Prima di inserire valori, prepara un elenco di nomi, senza i segreti. Per ciascun nome, devi stabilire tre cose: quale ambiente lo utilizza, dove viene eseguito il codice che legge la variabile e quando serve il valore.

L'ambiente Development è destinato allo sviluppo locale. Preview è per i deployment di anteprima e Production per la versione pubblicata principale. Preview può avere impostazioni specifiche per un ramo Git: queste sostituiscono le impostazioni generali di Preview con lo stesso nome.

In un progetto Next.js, le variabili senza NEXT_PUBLIC_ sono disponibili per impostazione predefinita sul server. Il prefisso NEXT_PUBLIC_ consente di incorporare il valore nel JavaScript inviato al browser. È adatto a un'impostazione esplicitamente pubblica, come un'etichetta di versione non segreta, ma non a una chiave API privata. Anche senza questo prefisso, il codice dell'applicazione non deve restituire manualmente un segreto al client.

Se non hai ancora identificato il framework, chiedi all'agente di individuarlo nei file del progetto. Il confronto tra Astro e Next.js può aiutarti a capire le differenze; non puoi applicare la regola NEXT_PUBLIC_ a ogni applicazione React.

La configurazione dell'hosting è una delle attività da svolgere quando si lavora a un'applicazione con un agente IA.

Come aggiungere una variabile a un progetto Vercel#

Esegui tu i passaggi nella dashboard ufficiale. Non dare all'agente una chiave reale da inserire nel modulo e non allegare uno screenshot che ne mostri il valore.

1. Apri la dashboard Vercel e seleziona il progetto corretto. Non basarti soltanto sulla corrispondenza del nome del repository: verifica di configurare l'applicazione che intendi aprire.
2. Nella barra laterale delle impostazioni del progetto, apri Environment Variables.
3. In Name, inserisci il nome letto dall'applicazione, per esempio SERVICE_API_KEY. È un nome d'esempio; se il codice ne prevede un altro, usane l'esatta grafia.
4. In Value, inserisci il valore dal tuo archivio delle credenziali. Non inserirlo nel codice sorgente, in una chat o in un log di verifica.
5. Seleziona l'ambiente che necessita dell'impostazione. Usa Preview per verificare una versione di anteprima e Production per la versione principale. Non assegnare automaticamente lo stesso segreto a tutti gli ambienti.
6. Se l'impostazione di Preview si applica a un ramo specifico, verifica il ramo selezionato e gli eventuali override con lo stesso nome.
7. Fai clic su Save.

Vercel rende disponibili le variabili del progetto sia durante la build sia quando vengono eseguite le Vercel Functions lato server. Tuttavia, la disponibilità di un valore all'interno di Vercel non significa che possa essere inviato al browser: dipende dal codice dell'applicazione e dalle regole del framework.

Perché dopo Save serve un nuovo deployment#

Salvare una variabile non modifica i deployment esistenti. La documentazione Vercel richiede di ridistribuire il progetto perché la nuova impostazione sia disponibile nella versione che usi.

Quando lavori tramite Git, puoi creare un nuovo deployment Production inviando un commit al ramo indicato in Production Branch e un deployment Preview inviandolo a un altro ramo. Non dare per scontato che il ramo principale sia sempre main: verifica l'impostazione del progetto. Deve trattarsi di una normale release concordata del progetto, senza aggiungere al commit un file contenente segreti.

Dopo aver avviato il deployment, attendi il completamento della build e apri l'URL del nuovo deployment. Annota il suo URL, l'ambiente e il ramo. Se controlli il vecchio URL di un singolo deployment, le nuove impostazioni non saranno visibili.

Next.js prevede un'altra condizione: i riferimenti come process.env.NEXT_PUBLIC_RELEASE_LABEL vengono sostituiti con i relativi valori durante next build. Il valore viene fissato al termine della build. Modificare l'impostazione senza una nuova build non riscriverà il JavaScript lato client già inviato.

Come verificare il risultato senza esporre la chiave#

Inizia con un esempio sicuro: un'etichetta esplicitamente non segreta, chiamata NEXT_PUBLIC_RELEASE_LABEL, con valore preview-check. Sono un nome e un testo d'esempio, non una chiave né un test eseguito qui. Se un'applicazione Next.js legge questa variabile direttamente tramite process.env.NEXT_PUBLIC_RELEASE_LABEL, dopo una nuova build può mostrare l'etichetta nel punto previsto dell'interfaccia. Questa verifica conferma solo che l'impostazione pubblica è stata applicata.

Una chiave privata si verifica in modo diverso. Non mostrare il suo valore, una sua parte, la sua lunghezza o l'intero process.env. Non creare un URL pubblico che restituisca il contenuto della variabile. Per prima cosa, controlla soltanto se l'impostazione è «presente / assente» sul server, poi verifica separatamente la funzione dell'applicazione che usa il servizio. La presenza di un'impostazione non dimostra che la chiave sia valida o abbia le autorizzazioni necessarie.

Puoi registrare i risultati senza includere segreti:

• il progetto, l'ambiente e il ramo corrispondono a quelli selezionati durante la configurazione;
• stai controllando l'URL di un nuovo deployment creato dopo aver salvato la variabile;
• la build è terminata e la funzione richiesta dell'applicazione è stata eseguita su dati di test sicuri;
• il segreto non è esposto nel browser, nelle risposte API, nei log o nelle conversazioni.

Se la funzione effettua un pagamento, invia un messaggio o compie un'altra azione con conseguenze, usa la modalità di test prevista dal servizio. Verificare la configurazione non autorizza, di per sé, un'operazione reale.

Cosa verificare se il valore è ancora undefined#

undefined significa che in quel punto di accesso non è stato ottenuto alcun valore. Verifica nome, ambiente e versione nell'ordine, senza modificare tutte le impostazioni insieme.

Dopo aver verificato il nome, l'ambiente e la nuova versione, un errore nella funzione non dimostra comunque che sia stato causato dalla variabile. Esamina lo specifico errore nel codice lato server senza pubblicare dati diagnostici che contengono segreti. Questa guida non garantisce di risolvere ogni risposta HTTP 500.

Passare al proprio server richiede una procedura diversa: consulta la guida al deployment di un progetto con Coolify. I nomi dei pulsanti e i passaggi di configurazione di Vercel non si applicano a Coolify.

Vai ad Ailoot.