Tipizzare le variabili d’ambiente
Assegni a process.env un tipo preciso e validato.
Tipizzare le variabili d’ambiente è una lezione TypeScript Academy gratuita su CoddyKit. Questa è la lezione 1 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 TypeScript Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso TypeScript Academy include 4 lezioni in totale.
Il problema di process.env
In Node, process.env è tipizzato come Record<string, string | undefined>. Ogni variabile potrebbe mancare e tutto è una stringa, quindi l'accesso diretto non è sicuro né tipizzato.
Dichiarare un'interfaccia Env tipizzata
Si inizia descrivendo la configurazione effettivamente richiesta dall'app con un'interfaccia precisa, che includa i tipi corretti e distingua i campi obbligatori da quelli facoltativi.
interface Env {
PORT: number;
NODE_ENV: "development" | "production";
DATABASE_URL: string;
DEBUG?: boolean; // optional
}Leggere i valori grezzi
Tutti i valori arrivano come stringhe o undefined. È necessario leggerli in modo difensivo, perché le chiavi potrebbero semplicemente non essere presenti.
const rawPort = process.env.PORT; // string | undefined
const rawEnv = process.env.NODE_ENV; // string | undefinedVariabili obbligatorie e facoltative
Alcune variabili devono esistere perché l'app possa funzionare; per altre esistono valori predefiniti appropriati. Un helper per i valori obbligatori segnala chiaramente l'errore quando uno di essi manca.
function required(name: string): string {
const v = process.env[name];
if (v === undefined) throw new Error("Missing env: " + name);
return v;
}Analizzare i numeri
Le variabili numeriche richiedono conversione e validazione, poiché parseInt può produrre NaN. È opportuno racchiudere il parsing in un helper, così gli input errati vengono rifiutati immediatamente.
function num(name: string): number {
const n = Number(required(name));
if (Number.isNaN(n)) throw new Error(name + " is not a number");
return n;
}Analizzare i booleani
I booleani arrivano come stringhe, ad esempio "true". È necessario normalizzarli esplicitamente, invece di affidarsi alla valutazione di verità di una stringa non vuota.
function bool(name: string, def = false): boolean {
const v = process.env[name];
if (v === undefined) return def;
return v === "true" || v === "1";
}Creare la configurazione tipizzata
Si assemblano i valori analizzati in un unico oggetto che corrisponde all'interfaccia Env. Da questo momento, il resto dell'app usa la configurazione tipizzata e non accede mai direttamente a process.env.
const env: Env = {
PORT: num("PORT"),
NODE_ENV: required("NODE_ENV") as Env["NODE_ENV"],
DATABASE_URL: required("DATABASE_URL"),
DEBUG: bool("DEBUG"),
};Limitare le unioni di stringhe
Per le variabili che ammettono un insieme fisso di valori, si esegue la validazione rispetto a quell'insieme, così un valore imprevisto non può passare inosservato come tipo literal errato.
function oneOf<T extends string>(name: string, allowed: readonly T[]): T {
const v = required(name) as T;
if (!allowed.includes(v)) throw new Error(name + " invalid");
return v;
}Centralizzare l'accesso
Si esporta l'unico oggetto env da un modulo centralizzato. Ogni consumer lo importa, ottenendo la tipizzazione completa e un unico punto in cui modificare la logica di parsing.
export const config = env;
// elsewhere: import { config } from "./config";Aggiungere definizioni a ProcessEnv (facoltativo)
È possibile dichiarare una module augmentation per NodeJS.ProcessEnv per tipizzare l'accesso diretto, ma un oggetto di configurazione analizzato è più sicuro perché convalida e converte anche i valori.
// declare global { namespace NodeJS { interface ProcessEnv { PORT: string } } }Perché conviene un oggetto di configurazione tipizzato
Una configurazione analizzata e convalidata offre tipi corretti (numeri, booleani e unioni), garantisce la presenza delle variabili obbligatorie e fornisce un unico import per tutta l'app, invece di letture non sicure e distribuite di process.env.
Verifica rapida
Verifica rapida di questa lezione.
Riepilogo
Si dichiara un'interfaccia Env tipizzata, quindi si analizza process.env con helper che convertono e convalidano i valori (numeri, booleani e unioni di stringhe) e segnalano un errore se mancano variabili obbligatorie. Si esporta un unico oggetto config tipizzato, così l'app non accede mai direttamente a process.env.
Domande Frequenti
La lezione «Tipizzare le variabili d’ambiente» è gratuita?
Sì — il testo completo di «Tipizzare le variabili d’ambiente» è 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 TypeScript Academy, passa a CoddyKit PRO. Il corso TypeScript Academy include 4 lezioni in totale.
Cosa imparerò in «Tipizzare le variabili d’ambiente»?
Assegni a process.env un tipo preciso e validato. Eserciti TypeScript 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 TypeScript Academy?
Non è richiesta alcuna esperienza precedente. TypeScript 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 1 di 4.
Quanto tempo richiede la lezione «Tipizzare le variabili d’ambiente»?
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 TypeScript Academy?
Sì. Ogni lezione TypeScript 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
- Tipizzare le variabili d’ambiente
- Configurazione validata tramite schema
- Livelli di configurazione e valori predefiniti
- Segreti e type safety