.env File در توسعه موبایل: چیست، کاربرد و اصل عملکرد

.env File چیست و چرا به آن نیاز داریم

.env File یک فایل پیکربندی است که متغیرهای محیطی را در قالب متنی ساده KEY=VALUE ذخیره می‌کند. هر خط شامل یک متغیر است: نام کلید و مقدار آن که با علامت مساوی از هم جدا شده‌اند.

فایل‌های .env یک مشکل اساسی در توسعه نرم‌افزار مدرن را حل می‌کنند: محیط‌های مختلف (محلی، آزمایشی، تولیدی) به تنظیمات کاملاً متفاوتی نیاز دارند. URL سرور API در ماشین محلی http://localhost:8080 است، در سرور تولیدی — https://api.production.com. اگر این مقادیر به طور ثابت در کد برنامه نوشته شده باشند، هر ساخت برای محیط متفاوت نیاز به تغییر کد منبع دارد.

رویه ذخیره‌سازی پیکربندی خارج از کد اصلی برنامه در مانیفست The Twelve-Factor App (2011) استاندارد شد که متغیرهای محیطی را به عنوان تنها راه صحیح پیکربندی برنامه معرفی کرد. بر اساس نظرسنجی JetBrains Developer Ecosystem (2024)، بیش از 67% توسعه‌دهندگان موبایل از فایل‌های .env در پروژه‌های خود استفاده می‌کنند.

برای توسعه موبایل، .env مزیت اضافی دارد: مقادیر در مرحله ساخت از طریق Gradle (Android) یا xcconfig (iOS) جایگزین می‌شوند که امکان ایجاد ساخت‌های جداگانه برای توسعه، استیجینگ و تولید را بدون تغییر کد منبع فراهم می‌کند.

.env به ویژه در کار تیمی مفید است: هر توسعه‌دهنده یک .env محلی خود را با تنظیمات مخصوص محیط خود (مسیر به DB محلی، کلیدهای API دیباگ) ایجاد می‌کند و تنظیمات مشترک در .env.example در مخزن ثبت می‌شود. این کار شرایطی را که پس از git pull ساخت به دلیل عدم وجود متغیر محیطی که توسعه‌دهنده از آن بی‌خبر بوده خراب می‌شود، از بین می‌برد. عضو جدید تیم به سادگی .env.example را به .env کپی کرده و مقادیر محلی خود را پر می‌کند.

نحو و ساختار .env File

فرمت .env بسیار ساده است: هر خط یک متغیر به شکل KEY=VALUE است. فاصله‌های اطراف علامت مساوی معمولاً نادیده گرفته می‌شوند، اما در اکثر کتابخانه‌ها بخشی از مقدار محسوب می‌شوند، بنابراین بهتر است از آنها اجتناب کنید.

قوانین اصلی نوشتار

نظرات با علامت # شروع می‌شوند — کل خط بعد از آن نادیده گرفته می‌شود. خطوط خالی نیز رد می‌شوند. اگر مقدار حاوی فاصله باشد، در گیومه‌های دوتایی یا تکی قرار می‌گیرد.

# تنظیمات اصلی محیط
APP_NAME=MyMobileApp
APP_ENV=development

# پیکربندی API
API_BASE_URL=http://localhost:3000/api
API_TIMEOUT=30000

# داده‌های حساس
DB_PASSWORD=secret_password_123
JWT_SECRET=your_jwt_secret_key

انواع مقادیر و escape کردن

همه متغیرها در .env رشته هستند، اما کتابخانه‌های بارگذاری می‌توانند آنها را به نوع مورد نظر تبدیل کنند. برای escape کردن کاراکترهای ویژه از بک‌اسلش و گیومه استفاده می‌شود. اگر مقدار حاوی کاراکتر # به عنوان بخشی از متن است، باید آن را به صورت \# escape کنید.

• رشته‌ها — بدون گیومه یا در گیومه: KEY=value یا KEY="value with spaces"
• اعداد — بدون گیومه نوشته می‌شوند: PORT=8080
• مقادیر بولی — رشته‌های true/false: DEBUG=true
• چندخطی — بک‌اسلش در انتهای خط: KEY=line1\
line2
• جانشینی — در برخی parserها: DB_URL=${DB_HOST}:${DB_PORT}

هنگام بارگذاری .env، کتابخانه‌ها می‌توانند درون‌یابی متغیرها را انجام دهند — مقادیر برخی کلیدها را در داخل دیگران جایگذاری کنند. به عنوان مثال، متغیر DATABASE_URL=postgres://${DB_USER}:${DB_PASS}@localhost/db مقادیر DB_USER و DB_PASS را از همان فایل باز می‌کند.

ادغام .env File در پروژه‌های موبایل

روش اتصال .env به پلتفرم بستگی دارد. Android از پلاگین‌های Gradle، iOS از فایل‌های پیکربندی xcconfig و راه‌حل‌های چندسکویی مانند Flutter از کتابخانه‌های تخصصی استفاده می‌کنند.

Android و Gradle: تنظیم BuildConfig

در Android، .env از طریق پلاگین gradle-dotenv بارگذاری می‌شود. پلاگین .env را از ریشه پروژه خوانده و مقادیر را به BuildConfig اضافه می‌کند، پس از آن در کد Kotlin یا Java از طریق فیلدهای تولید شده در دسترس هستند.

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

android {
    buildFeatures {
        buildConfig = true
    }
}

kotlin {
    // دسترسی در کد: BuildConfig.API_BASE_URL
    buildConfigField("String", "API_BASE_URL",
        "\"" + dotenv.get("API_BASE_URL") + "\"")
}

iOS و Xcode: اتصال Config

در iOS، متغیرهای محیطی معمولاً از طریق فایل‌های xcconfig پیکربندی می‌شوند. برای بارگذاری .env در Swift از کتابخانه DotEnv یا مکانیزم داخلی Info.plist با کلیدهای سفارشی استفاده می‌شود.

// بارگذاری .env در پروژه 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 و Dart: کتابخانه flutter_dotenv

برای Flutter بسته flutter_dotenv وجود دارد که متغیرها را از .env در زمان مقداردهی اولیه برنامه بارگذاری می‌کند. فایل .env در ریشه پروژه قرار می‌گیرد و متغیرها از طریق کلاس dotenv در دسترس می‌شوند.

// pubspec.yaml
dependencies:
  flutter_dotenv: ^5.1

// main.dart — بارگذاری هنگام راه‌اندازی
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));
}

هر سه رویکرد یک اصل مشترک دارند: .env در مرحله ساخت یا هنگام راه‌اندازی برنامه بارگذاری می‌شود، مقادیر ذخیره و در کد از طریق ثابت‌های تولید شده استفاده می‌شوند. این کار از ورود داده‌های حساس به مخزن جلوگیری می‌کند.

برای React Native از بسته react-native-config استفاده می‌شود که در مرحله ساخت به طور خودکار کلاس BuildConfig برای Android و ثابت‌ها را در Info.plist برای iOS از یک فایل .env در ریشه پروژه تولید می‌کند. این به ویژه برای استارتاپ‌هایی که از Expo یا bare workflow استفاده می‌کنند راحت است: یک .env در سطح ریشه کافی است و همه پلتفرم‌ها متغیرهای محیطی یکسانی را بدون تکرار پیکربندی دریافت می‌کنند.

امنیت و بهترین روش‌های .env File

با وجود تمام مزایا، .env یک راه‌حل کامل برای ذخیره اسرار در محیط تولید نیست. این فایل سطح پایه‌ای از محافظت را فراهم می‌کند، اما در صورت استفاده نادرست می‌تواند منجر به نشت داده‌های محرمانه شود.

محافظت از طریق .gitignore

مهمترین قانون — .env هرگز نباید وارد سیستم کنترل نسخه مخزن شود. فایل بلافاصله پس از ایجاد به .gitignore اضافه می‌شود و فقط فایل نمونه .env.example با مقادیر خالی یا ساختگی به مخزن commit می‌شود.

# .env.example — commit به مخزن
APP_NAME=
APP_ENV=development
API_BASE_URL=http://localhost:3000
API_TIMEOUT=30000
# DB_PASSWORD — حتی در نمونه هم مشخص نکنید!
# JWT_SECRET — حتی در نمونه هم مشخص نکنید!

# .gitignore
# فایل‌های Dotenv
.env
.env*.local

جایگزین‌های محیط تولید

برای پروژه‌های تولیدی توصیه می‌شود از راه‌حل‌های حرفه‌ای مدیریت اسرار استفاده شود. .env در تولید فقط در صورتی مجاز است که فایل خارج از document-root سرور قرار داشته باشد و مجوزهای دسترسی سختگیرانه داشته باشد.

• AWS Secrets Manager — ذخیره‌سازی ابری اسرار با چرخش کلید و ممیزی دسترسی
• Google Secret Manager — سرویس Google Cloud برای ذخیره کلیدهای API و رمزهای عبور
• HashiCorp Vault — ابزاری با اسرار پویا و رمزگذاری سمت سرور
• Firebase Remote Config — پیکربندی ابری با آزمایش A/B برای برنامه‌های موبایل
• GitLab CI/CD Variables — ذخیره‌سازی داخلی اسرار برای خطوط لوله ساخت

بر اساس Snyk State of Open Source Security (2024)، نشت فایل‌های .env از طریق مخازن عامل بیش از 12% از تمام حوادث افشای کلیدهای API در میان شرکت‌های مورد بررسی بوده است. استفاده از یک مدیر اسرار جداگانه این خطر را به صفر می‌رساند.

محافظت اضافی با پیاده‌سازی هوک‌های pre-commit با استفاده از ابزارهایی مانند husky و lint-staged حاصل می‌شود که بررسی می‌کنند آیا توسعه‌دهنده به طور تصادفی .env را به commit اضافه کرده است یا خیر. ابزارهایی مانند git-secrets (AWS) و talisman هر commit را برای الگوهای کلیدهای API، توکن‌ها و رمزهای عبور اسکن کرده و در صورت تشخیص، commit را مسدود می‌کنند. برای خطوط لوله CI توصیه می‌شود بررسی detect-secrets اضافه شود — یک اسکنر خودکار که حتی در صورت خطای توسعه‌دهنده اجازه ورود فایل .env به مخزن را نمی‌دهد.