File .env nello sviluppo mobile: cos'è, scopo e principio di funzionamento

Cos'è .env File e a cosa serve

.env File è un file di configurazione che memorizza le variabili d'ambiente in un semplice formato testo KEY=VALUE. Ogni riga contiene una variabile: il nome della chiave e il suo valore, separati da un segno di uguale.

I file .env risolvono un problema fondamentale dello sviluppo moderno: ambienti diversi (locale, test, produzione) richiedono impostazioni completamente diverse. L'URL del server API su una macchina locale è http://localhost:8080, su un server di produzione è https://api.production.com. Se questi valori sono hardcodati direttamente nel codice dell'applicazione, ogni compilazione per un ambiente diverso richiede la modifica del codice sorgente.

La pratica di memorizzare la configurazione al di fuori del codice principale dell'applicazione è stata standardizzata nel manifesto The Twelve-Factor App (2011), che ha identificato le variabili d'ambiente come l'unico modo corretto per configurare un'applicazione. Secondo il sondaggio JetBrains Developer Ecosystem (2024), più del 67% degli sviluppatori mobile utilizza file .env nei propri progetti.

Per lo sviluppo mobile, .env offre un vantaggio aggiuntivo: i valori vengono sostituiti in fase di compilazione tramite Gradle (Android) o xcconfig (iOS), consentendo di creare build separate per sviluppo, staging e produzione senza modificare il codice sorgente.

.env è particolarmente utile quando si lavora in team: ogni sviluppatore crea il proprio .env locale con impostazioni per il proprio ambiente (percorso DB locale, chiavi API di debug), mentre le impostazioni comuni vengono fissate in .env.example nel repository. Questo elimina la situazione in cui dopo un git pull la build di uno sviluppatore si rompe a causa di una variabile d'ambiente mancante di cui non era a conoscenza. Un nuovo membro del team copia semplicemente .env.example in .env e inserisce i propri valori locali.

Sintassi e struttura del file .env

Il formato .env è estremamente semplice: ogni riga è una variabile nella forma KEY=VALUE. Gli spazi attorno al segno di uguale di solito vengono ignorati, ma nella maggior parte delle librerie sono considerati parte del valore, quindi è meglio evitarli.

Regole di base per la scrittura

I commenti iniziano con il carattere # — l'intera riga dopo di esso viene ignorata. Anche le righe vuote vengono saltate. Se il valore contiene spazi, viene racchiuso tra virgolette doppie o singole.

# Impostazioni di base dell'ambiente
APP_NAME=MyMobileApp
APP_ENV=development

# Configurazione API
API_BASE_URL=http://localhost:3000/api
API_TIMEOUT=30000

# Dati sensibili
DB_PASSWORD=secret_password_123
JWT_SECRET=your_jwt_secret_key

Tipi di valori e escaping

Tutte le variabili in .env sono stringhe, ma le librerie di caricamento possono convertirle nel tipo necessario. Per eseguire l'escaping dei caratteri speciali si usano backslash e virgolette. Se un valore contiene il carattere # come parte del testo, deve essere escaped come \#.

• Stringhe — senza virgolette o tra virgolette: KEY=value o KEY="value with spaces"
• Numeri — scritti senza virgolette: PORT=8080
• Valori booleani — stringhe true/false: DEBUG=true
• Multilinea — backslash alla fine della riga: KEY=line1\
line2
• Sostituzione — in alcuni parser: DB_URL=${DB_HOST}:${DB_PORT}

Durante il caricamento di .env, le librerie possono eseguire interpolazione di variabili — sostituire i valori di alcune chiavi all'interno di altre. Ad esempio, la variabile DATABASE_URL=postgres://${DB_USER}:${DB_PASS}@localhost/db espanderà DB_USER e DB_PASS dallo stesso file.

Integrazione del file .env in progetti mobile

Il metodo di connessione di .env dipende dalla piattaforma. Android utilizza plugin Gradle, iOS — file di configurazione xcconfig, e le soluzioni multipiattaforma come Flutter — librerie specializzate.

Android e Gradle: configurazione di BuildConfig

Su Android, .env viene caricato tramite il plugin gradle-dotenv. Il plugin legge .env dalla radice del progetto e aggiunge i valori a BuildConfig, dopodiché sono disponibili nel codice Kotlin o Java tramite campi generati.

// build.gradle.kts (livello app)
plugins {
    id("co.uzzu.dotenv") version "4.0.0"
}

android {
    buildFeatures {
        buildConfig = true
    }
}

kotlin {
    // Accesso nel codice: BuildConfig.API_BASE_URL
    buildConfigField("String", "API_BASE_URL",
        "\"" + dotenv.get("API_BASE_URL") + "\"")
}

iOS e Xcode: connessione di Config

Su iOS, le variabili d'ambiente vengono solitamente configurate tramite file xcconfig. Per caricare .env in Swift si usa la libreria DotEnv o il meccanismo integrato Info.plist con chiavi personalizzate.

// Caricamento di .env in progetto Swift
import DotEnv

struct AppConfig {
    static func load() {
        let env = DotEnv(Bundle.main)
        env.load()

        let apiURL = ProcessInfo.processInfo
            .environment["API_BASE_URL"] ??
            "https://default.api.com"
    }
}

Flutter e Dart: libreria flutter_dotenv

Per Flutter esiste il pacchetto flutter_dotenv, che carica le variabili da .env durante l'inizializzazione dell'applicazione. Il file .env viene posizionato nella radice del progetto e le variabili diventano disponibili tramite la classe dotenv.

// pubspec.yaml
dependencies:
  flutter_dotenv: ^5.1

// main.dart — caricamento all'avvio
import 'package:flutter_dotenv/flutter_dotenv.dart';

void main() async {
  await dotenv.load(fileName: '.env');
  var apiUrl = dotenv.get('API_BASE_URL');
  runApp(MyApp(baseUrl: apiUrl));
}

Tutti e tre gli approcci condividono un principio comune: .env viene caricato in fase di compilazione o all'avvio dell'applicazione, i valori vengono memorizzati nella cache e utilizzati nel codice tramite costanti generate. Questo impedisce ai dati sensibili di finire nel repository.

Per React Native si usa il pacchetto react-native-config, che in fase di compilazione genera automaticamente una classe BuildConfig per Android e costanti in Info.plist per iOS da un singolo file .env nella radice del progetto. Questo è particolarmente comodo per le startup che usano Expo o bare workflow: un singolo .env a livello di radice è sufficiente affinché tutte le piattaforme ricevano le stesse variabili d'ambiente senza duplicare le configurazioni.

Sicurezza e migliori pratiche del file .env

Nonostante tutti i vantaggi, .env non è una soluzione completa per memorizzare segreti in ambiente di produzione. Fornisce un livello base di protezione, ma se usato in modo errato, può portare a perdita di dati riservati.

Protezione tramite .gitignore

La regola più importante — .env non deve mai finire nel sistema di controllo versione del repository. Il file viene aggiunto a .gitignore immediatamente dopo la creazione, e solo il file di esempio .env.example con valori vuoti o fittizi viene committato nel repository.

# .env.example — committato nel repository
APP_NAME=
APP_ENV=development
API_BASE_URL=http://localhost:3000
API_TIMEOUT=30000
# DB_PASSWORD — non specificare nemmeno nell'esempio!
# JWT_SECRET — non specificare nemmeno nell'esempio!

# .gitignore
# File Dotenv
.env
.env*.local

Alternative per l'ambiente di produzione

Per i progetti in produzione, si raccomanda di utilizzare soluzioni professionali di gestione dei segreti. .env in produzione è accettabile solo se il file si trova al di fuori del document-root del server e ha permessi di accesso rigorosi.

• AWS Secrets Manager — archivio cloud di segreti con rotazione delle chiavi e audit di accesso
• Google Secret Manager — servizio Google Cloud per memorizzare chiavi API e password
• HashiCorp Vault — strumento con segreti dinamici e crittografia lato server
• Firebase Remote Config — configurazione cloud con test A/B per applicazioni mobile
• GitLab CI/CD Variables — archivio segreti integrato per pipeline di compilazione

Secondo Snyk State of Open Source Security (2024), la perdita di file .env attraverso i repository è stata la causa di oltre il 12% di tutti gli incidenti di divulgazione di chiavi API tra le aziende intervistate. L'uso di un gestore di segreti dedicato riduce questo rischio a zero.

Una protezione aggiuntiva si ottiene implementando hook di pre-commit utilizzando strumenti come husky e lint-staged, che verificano se uno sviluppatore ha accidentalmente aggiunto .env a un commit. Strumenti come git-secrets (AWS) e talisman analizzano ogni commit alla ricerca di pattern di chiavi API, token e password, bloccando il commit in caso di rilevamento. Per le pipeline CI, si raccomanda di aggiungere detect-secrets — uno scanner automatico che non permetterà a un file .env di entrare nel repository nemmeno se lo sviluppatore commette un errore.