Environment variables hold the configuration and secrets your app needs at build time and at runtime, such as API keys, database URLs and feature flags, without any of it living in your repository…

Variabili d'Ambiente

Le variabili d'ambiente contengono la configurazione e i segreti di cui la tua app ha bisogno in fase di compilazione e durante l'esecuzione, come chiavi API, URL dei database e feature flag, senza che nulla di questo risieda nel repository. Questa guida copre dove risiedono in Orbit, come funzionano lo scope e la precedenza, come contrassegnare un valore come segreto, l'importazione e l'esportazione in massa, e gli errori che producono una variabile indefinita.

Dove Risiedono

Apri il tuo progetto in Orbit e fai clic sulla scheda Env vars, in /orbit/<project-id>/env-vars.

La pagina è organizzata in sezioni:

All environments in alto: variabili a livello di progetto, disponibili in ogni compilazione.
Una sezione comprimibile per ambiente (Production, Staging e anteprime) che contiene gli override di quell'ambiente.

Sopra l'elenco c'è una casella di ricerca e un filtro Secrets only, che sono il modo più veloce per navigare un elenco lungo.

Come Funziona lo Scope

Scope	Cosa influenza
All environments (a livello di progetto)	Iniettato in ogni compilazione di questo progetto
Override a livello di ambiente	Si applica solo a quell'ambiente, e prevale sul valore a livello di progetto con la stessa chiave

Il sottotitolo della pagina esprime la regola chiaramente: le variabili a livello di progetto sono disponibili in ogni compilazione, e gli override a livello di ambiente hanno la precedenza.

Una configurazione tipica è una variabile a livello di progetto DATABASE_URL che punta a un database di test, con un override a livello di produzione che punta a quello reale. Le compilazioni di produzione ottengono il database reale, tutto il resto ottiene quello di test, e nulla di ciò che aggiungi in seguito trapela accidentalmente le credenziali di produzione in un'anteprima.

C'è anche un controllo Available in sulle variabili a livello di progetto, che ti consente di escludere tipi di ambiente particolari (production, staging, preview) da una variabile che è altrimenti a livello di progetto.

I dettagli completi sullo scoping per ambiente, comprese le ragioni di sicurezza, si trovano in Configurazione delle Variabili d'Ambiente Per Ambiente.

Una variabile a livello di progetto viene iniettata nelle compilazioni di anteprima dei branch, e gli URL di anteprima sono pubblicamente raggiungibili da chiunque abbia il link. Le credenziali del database di produzione, le chiavi di pagamento live e i token di amministrazione devono essere limitati solo alla produzione. Questa è la cosa più importante da affrontare correttamente in questa pagina.

Aggiunta di una Variabile

Scorri fino al modulo Add variable in fondo alla scheda Env vars.
Inserisci la KEY, ad esempio NEXT_PUBLIC_API_URL.
Inserisci il value.
Scegli uno Scope: All environments (project-wide), o un override di un ambiente specifico.
Se hai scelto project-wide, usa i pulsanti Available in per deselezionare i tipi di ambiente a cui questa variabile non deve arrivare.
Seleziona Mark as secret per qualsiasi cosa sensibile.
Fai clic su Add.

Il modulo ti dice cosa sta per fare prima di confermare: un override di ambiente mostra un avviso che dice che si applicherà solo alle compilazioni di quell'ambiente, e una variabile project-wide ristretta mostra quali tipi di ambiente riceveranno l'iniezione.

Quando i Cambiamenti Hanno Effetto

L'aggiunta, la modifica o l'eliminazione di una variabile non modifica la distribuzione attualmente live. Le variabili vengono iniettate quando viene eseguita una compilazione, quindi la modifica si applica dalla successiva distribuzione in poi. Ridistribuisci dopo aver modificato qualsiasi cosa su cui la tua app dipende.

Orbit è esplicito su questo. Apri la pagina di dettagli di una distribuzione e, se la configurazione è cambiata da quando è stata compilata, riceverai un avviso Environment variables updated since this deployment che ti dice che la modifica non avrà effetto fino a quando non ridistribuisci.

Segreti

Seleziona Mark as secret per qualsiasi cosa che non incollheresti in una chat: chiavi API, password dei database, token, chiavi di firma.

I valori segreti sono mascherati nel pannello e hanno un badge secret. I valori non segreti mostrano un marcatore (plain).

Il valore di un segreto non può essere letto di nuovo dopo che è stato salvato, non da te e non da nessun altro nel pannello. Puoi sostituirlo (fai clic sull'icona di modifica, digita un nuovo valore, salva) ma non puoi rivelarlo. Mantieni una copia personale in un password manager prima di salvarlo qui.

Orbit traccia anche da quanto tempo un valore è in uso e mostra un badge di età sulle variabili più vecchie, con un suggerimento che ne consiglia la rotazione. È un avviso, non un obbligo.

Modifica e Eliminazione

Fai clic sull'icona di modifica accanto a una variabile per cambiarne il valore. Fai clic su Delete per rimuoverla e conferma: il dialogo avverte che le compilazioni che dipendono da essa si interromperanno, che è la descrizione accurata di ciò che accade nella distribuzione successiva.

Importazione ed Esportazione in Massa

Due pulsanti nella parte superiore della scheda gestiscono il lavoro in massa.

Import .env apre una casella di incolla. Incolla il contenuto di un file .env, scegli uno scope, e Orbit ti dice quante variabili ha rilevato e quante maricherà come segreto. Contrassegna automaticamente le chiavi in base ai loro nomi, quindi qualsiasi cosa contenga SECRET, TOKEN, KEY, PASSWORD e simili viene contrassegnata come segreto prima dell'importazione. C'è un'opzione Overwrite existing variables with the same key, disabilitata per impostazione predefinita.

Download .env produce un modello contenente i nomi delle variabili soltanto, senza valori. È pensato per essere condiviso con un collega che poi compila i propri valori, non per essere utilizzato come backup.

Il download di un modello .env non include mai valori, nemmeno per le variabili non segreto. Non c'è modo di esportare valori da Orbit. Se hai bisogno di una copia di un valore, prendilo da qualunque luogo l'abbia originariamente generato.

Copia di Variabili Tra Ambienti

Il pannello Copy variables between environments copia un'intera serie da uno scope a un altro. Scegli un From (a livello di progetto o un ambiente specifico) e un To, facoltativamente seleziona Overwrite variables that already exist in the target, e fai clic su Preview per vedere esattamente quante verranno aggiunte, aggiornate e saltate prima di confermare.

C'è anche una pagina Env sync check che confronta la produzione e lo staging chiave per chiave e segnala cosa c'è solo in uno, cosa differisce e cosa corrisponde. È lo strumento giusto per "perché lo staging funziona e la produzione no".

Condivisione di Variabili Tra Progetti

Se più progetti hanno bisogno della stessa credenziale, utilizza un env group anziché copiarla in ogni progetto. Vai a Orbit, poi Env groups, crea un gruppo, aggiungi variabili ad esso, e collega i progetti che ne hanno bisogno.

Le variabili del gruppo vengono iniettate in fase di compilazione, e le variabili a livello di progetto e a livello di ambiente hanno la precedenza sulle variabili del gruppo. Puoi avere fino a 20 gruppi su un account.

Note sul Framework

Quali variabili raggiungono il browser è deciso dal tuo framework, non da Orbit. Orbit inietta tutto ciò che è in scope; il framework decide cosa esporre.

Next.js: le chiavi con prefisso NEXT_PUBLIC_ sono inlineate nel bundle del browser in fase di compilazione. Tutto il resto rimane lato server.
Vite: le chiavi con prefisso VITE_ sono esposte al browser. Tutto il resto è solo in fase di compilazione.
App Node.js: tutto ciò che è in scope è su process.env durante la compilazione, e in runtime quando Server mode è attivato.

Non contrassegnare mai un valore come segreto e poi anche prefissoarlo con NEXT_PUBLIC_ o VITE_. Il flag segreto controlla solo se il pannello ti mostra il valore; il prefisso controlla se il tuo framework lo invia al browser di ogni visitatore. Il prefisso prevale.

Verifica di Ciò Che una Compilazione Ha Effettivamente Ricevuto

Ogni pagina di dettagli della distribuzione elenca le chiavi delle variabili d'ambiente che sono state iniettate in fase di compilazione, e le confronta con la tua configurazione attuale: aggiunte, modificate, rimosse e invariate. Le chiavi teal provengono da un override specifico dell'ambiente, quelle grigie da livello di progetto. I valori non vengono mai archiviati o mostrati, ma passare il mouse su una chiave fornisce un'impronta SHA-256, che è sufficiente per confermare che due ambienti contengono lo stesso valore senza rivelarlo.

Questa è la risposta definitiva a "la mia variabile sta effettivamente raggiungendo la compilazione". Controllalo prima di cambiare qualsiasi altra cosa.

Risoluzione dei Problemi

La variabile è indefinita in runtime. Controlla che la distribuzione sia successiva alla modifica, poi controlla che lo scope copra questo ambiente, poi controlla le regole del prefisso del framework sopra. In questo ordine.

Funziona in produzione ma non in un'anteprima. La variabile è limitata solo alla produzione, oppure una variabile a livello di progetto ha preview deselezionato sotto Available in. Di solito è intenzionale.

Funziona localmente ma non nella compilazione. Il tuo file locale .env non è nel repository, e non dovrebbe esserlo. Importalo con Import .env e scegli lo scope giusto.

Lo staging manca di tutto ciò che ha la produzione. Attiva Inherit production env vars in Settings, sotto Staging: environment variables, oppure usa Copy variables between environments.

Variabili di Ambiente