.env File în dezvoltarea mobilă: ce este, scopul și principiul de funcționare

Ce este .env File și de ce este necesar

.env File este un fișier de configurare în care se stochează variabilele de mediu într-un format text simplu KEY=VALUE. Fiecare linie conține o variabilă: numele cheii și valoarea acesteia separate prin semnul egal.

Fișierele .env rezolvă o problemă fundamentală a dezvoltării moderne: medii diferite (local, test, producție) necesită setări complet diferite. URL-ul serverului API pe mașina locală este http://localhost:8080, pe serverul de producție — https://api.production.com. Dacă aceste valori sunt încorporate direct în codul aplicației, fiecare compilare pentru un alt mediu necesită modificarea codului sursă.

Practica stocării configurației în afara codului principal al aplicației a fost standardizată în manifestul The Twelve-Factor App (2011), care a evidențiat variabilele de mediu ca singurul mod corect de configurare a aplicației. Conform sondajului JetBrains Developer Ecosystem (2024), peste 67% dintre dezvoltatorii mobili folosesc fișiere .env în proiectele lor.

Pentru dezvoltarea mobilă, .env oferă un avantaj suplimentar: valorile se înlocuiesc în etapa de compilare prin Gradle (Android) sau xcconfig (iOS), permițând crearea de compilări separate pentru dezvoltare, stagiere și producție fără modificarea codului sursă.

.env este deosebit de util în lucrul în echipă: fiecare dezvoltator își creează propriul .env local cu setări pentru mediul său (calea către baza de date locală, chei API de debug), iar setările comune sunt fixate în .env.example în depozit. Aceasta elimină situația când după git pull compilarea dezvoltatorului se strică din cauza lipsei unei variabile de mediu despre care nu știa. Noul membru al echipei copiază pur și simplu .env.example în .env și își completează valorile locale.

Sintaxa și structura .env File

Formatul .env este cât se poate de simplu: fiecare linie este o variabilă de forma KEY=VALUE. Spațiile din jurul semnului egal sunt de obicei ignorate, dar în majoritatea bibliotecilor sunt considerate parte a valorii, deci este mai bine să le evitați.

Reguli de bază de scriere

Comentariile încep cu simbolul # — întreaga linie după acesta este ignorată. Liniile goale sunt de asemenea omise. Dacă valoarea conține spații, se pune între ghilimele duble sau simple.

# Setări principale de mediu
APP_NAME=MyMobileApp
APP_ENV=development

# Configurație API
API_BASE_URL=http://localhost:3000/api
API_TIMEOUT=30000

# Date sensibile
DB_PASSWORD=secret_password_123
JWT_SECRET=your_jwt_secret_key

Tipuri de valori și escapare

Toate variabilele în .env sunt șiruri de caractere, dar bibliotecile de încărcare le pot converti în tipul necesar. Pentru escaparea caracterelor speciale se folosesc backslash-uri și ghilimele. Dacă valoarea conține simbolul # ca parte a textului, trebuie să fie escapat ca \#.

• Șiruri de caractere — fără ghilimele sau între ghilimele: KEY=value sau KEY="value with spaces"
• Numere — se scriu fără ghilimele: PORT=8080
• Valori booleene — șiruri true/false: DEBUG=true
• Multilinie — backslash la sfârșitul liniei: KEY=line1\
line2
• Substituire — în unele analizoare: DB_URL=${DB_HOST}:${DB_PORT}

La încărcarea .env, bibliotecile pot efectua interpolarea variabilelor — înlocuirea valorilor unor chei în interiorul altora. De exemplu, variabila DATABASE_URL=postgres://${DB_USER}:${DB_PASS}@localhost/db va deschide DB_USER și DB_PASS din același fișier.

Integrarea .env File în proiecte mobile

Modul de conectare a .env depinde de platformă. Android folosește pluginuri Gradle, iOS — fișiere de configurare xcconfig, iar soluțiile cross-platform precum Flutter — biblioteci specializate.

Android și Gradle: configurarea BuildConfig

În Android, .env se încarcă prin pluginul gradle-dotenv. Pluginul citește .env din rădăcina proiectului și adaugă valorile în BuildConfig, după care acestea sunt disponibile în codul Kotlin sau Java prin câmpuri generate.

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

android {
    buildFeatures {
        buildConfig = true
    }
}

kotlin {
    // Acces în cod: BuildConfig.API_BASE_URL
    buildConfigField("String", "API_BASE_URL",
        "\"" + dotenv.get("API_BASE_URL") + "\"")
}

iOS și Xcode: conectarea Config

În iOS, variabilele de mediu se configurează de obicei prin fișiere xcconfig. Pentru încărcarea .env în Swift se folosește biblioteca DotEnv sau mecanismul încorporat Info.plist cu chei personalizate.

// Încărcarea .env în proiectul 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 și Dart: biblioteca flutter_dotenv

Pentru Flutter există pachetul flutter_dotenv care încarcă variabilele din .env în timpul inițializării aplicației. Fișierul .env se plasează în rădăcina proiectului, iar variabilele devin disponibile prin clasa dotenv.

// pubspec.yaml
dependencies:
  flutter_dotenv: ^5.1

// main.dart — încărcare la pornire
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));
}

Toate cele trei abordări au un principiu comun: .env se încarcă în etapa de compilare sau la pornirea aplicației, valorile sunt stocate în cache și folosite în cod prin constante generate. Aceasta exclude pătrunderea datelor sensibile în depozit.

Pentru React Native se folosește pachetul react-native-config care în etapa de compilare generează automat clasa BuildConfig pentru Android și constante în Info.plist pentru iOS dintr-un singur fișier .env în rădăcina proiectului. Acest lucru este deosebit de convenabil pentru startup-urile care folosesc Expo sau bare workflow: un singur .env la nivel de rădăcină este suficient, iar toate platformele primesc aceleași variabile de mediu fără duplicarea configurațiilor.

Securitatea și cele mai bune practici .env File

În ciuda tuturor avantajelor, .env nu este o soluție completă pentru stocarea secretelor în mediul de producție. Oferă un nivel de bază de protecție, dar la utilizarea incorectă poate duce la scurgerea datelor confidențiale.

Protecția prin .gitignore

Cea mai importantă regulă — .env nu trebuie să ajungă niciodată în sistemul de control al versiunilor. Fișierul se adaugă în .gitignore imediat după creare, iar în depozit se comitează doar fișierul-șablon .env.example cu valori goale sau fictive.

# .env.example — comitat în depozit
APP_NAME=
APP_ENV=development
API_BASE_URL=http://localhost:3000
API_TIMEOUT=30000
# DB_PASSWORD — nu se indică nici în exemplu!
# JWT_SECRET — nu se indică nici în exemplu!

# .gitignore
# Fișiere Dotenv
.env
.env*.local

Alternative pentru mediul de producție

Pentru proiectele de producție se recomandă utilizarea soluțiilor profesionale de gestionare a secretelor. .env în producție este permis doar dacă fișierul se află în afara document-root-ului serverului și are drepturi de acces stricte.

• AWS Secrets Manager — stocare în cloud a secretelor cu rotație de chei și audit de acces
• Google Secret Manager — serviciul Google Cloud pentru stocarea cheilor API și parolelor
• HashiCorp Vault — instrument cu secrete dinamice și criptare pe partea serverului
• Firebase Remote Config — configurare în cloud cu testare A/B pentru aplicații mobile
• GitLab CI/CD Variables — stocare încorporată a secretelor pentru pipeline-uri de compilare

Conform Snyk State of Open Source Security (2024), scurgerea fișierelor .env prin depozite a fost cauza a peste 12% din toate incidentele de dezvăluire a cheilor API printre companiile chestionate. Utilizarea unui manager de secrete separat reduce acest risc la zero.

Protecția suplimentară se realizează prin implementarea hook-urilor pre-commit cu instrumente precum husky și lint-staged care verifică dacă dezvoltatorul nu a adăugat accidental .env în commit. Instrumente precum git-secrets (AWS) și talisman scanează fiecare commit pentru modele de chei API, token-uri și parole, blocând commit-ul la detectare. Pentru pipeline-urile CI se recomandă adăugarea verificării detect-secrets — un scaner automat care nu va lăsa fișierul .env să intre în depozit chiar și la eroarea dezvoltatorului.