Build Config در برنامه‌های موبایل — چیست، پیکربندی و اصل کار

Build Config در توسعه موبایل چیست

Build Config — مجموعه تنظیماتی است که فرایند کامپایل، ساخت و بسته‌بندی برنامه موبایل را تعیین می‌کند. کانفیگ بیلد شامل انتخاب پلتفرم هدف، حداقل نسخه SDK، فلگ‌های بهینه‌سازی، کلیدهای امضا و متغیرهای محیطی است.

پروژه‌های موبایل مدرن به‌ندرت تنها یک کانفیگ بیلد دارند. معمولاً چندین مورد دارند: debug (برای توسعه با دیباگ)، release (برای تولید با بهینه‌سازی)، staging (برای آزمایش با داده‌های واقعی) و فلیورهای مختلف (نسخه‌های نمایشی، کامل و سازمانی).

طبق نظرسنجی Gradle Build Tool Survey (2025)، به‌طور متوسط پروژه اندروید از 3.2 کانفیگ بیلد مختلف استفاده می‌کند و پروژه iOS — از 2.8. هر کانفیگ می‌تواند فلگ‌های کامپایل، گواهینامه‌های امضا و URL سرورهای خود را داشته باشد.

وظیفه اصلی Build Config خودکارسازی جابه‌جایی بین این کانفیگ‌هاست. به‌جای تغییر دستی URL سرور یا فلگ دیباگ، توسعه‌دهنده Build Variant موردنظر را در IDE انتخاب می‌کند و سیستم بیلد پارامترهای مربوطه را جایگزین می‌کند.

پیکربندی صحیح Build Config تأثیر حیاتی بر امنیت برنامه دارد: در بیلد debug لاگ‌های دقیق، بازرس پایگاه داده و endpointهای دیباگ فعال هستند که باید به‌طور فیزیکی از فایل release حذف شوند. Gradle این کار را از طریق Build Types حل می‌کند: در debug می‌توان فلگ debuggable true و در release — minifyEnabled true با ProGuard تنظیم کرد. iOS همان نتیجه را از طریق Swift Active Compilation Conditions به دست می‌آورد، جایی که کد داخل #if DEBUG در کانفیگ release کامپایل نمی‌شود.

Build Config در اندروید: Gradle و BuildConfig

اندروید از سیستم بیلد Gradle با دو مفهوم کلیدی استفاده می‌کند: Build Types و Product Flavors. ترکیب آن‌ها Build Variants را ایجاد می‌کند — هر واریانت کانفیگ کامل بیلد خود را دارد.

Build Types: debug و release

Build Type — کانفیگی است که تعیین می‌کند برنامه چگونه ساخته می‌شود. به‌طور پیش‌فرض Gradle دو نوع می‌سازد: debug (با دیباگ، بدون مبهم‌سازی) و release (با ProGuard/R8، امضاشده برای انتشار). توسعه‌دهنده می‌تواند انواع خود را اضافه کند: staging, benchmark, qa.

// build.gradle.kts
android {
    buildTypes {
        debug {
            isDebuggable = true
            buildConfigField("String", "API_URL", "\"http://dev.api.com\"")
        }
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
            buildConfigField("String", "API_URL", "\"https://prod.api.com\"")
        }
    }
}

Product Flavors: نسخه‌های برنامه

Product Flavors امکان ایجاد نسخه‌های مختلف یک برنامه از یک پایگاه کد را فراهم می‌کنند. مثلاً: نسخه رایگان با تبلیغات، نسخه پولی بدون تبلیغات و نسخه سازمانی با قابلیت‌های اضافه. هر فلیور می‌تواند applicationId، منابع و وابستگی‌های SDK خود را داشته باشد.

android {
    productFlavors {
        register("demo") {
            applicationId = "com.example.app.demo"
            versionNameSuffix = "-demo"
        }
        register("full") {
            applicationId = "com.example.app"
            versionNameSuffix = ""
        }
    }
}

کلاس BuildConfig: دسترسی از کد

Gradle برای هر Build Variant کلاس BuildConfig با فیلدهای کانفیگ تولید می‌کند. توسعه‌دهنده فیلدهای خود را از طریق buildConfigField اضافه می‌کند، و فیلدهای استاندارد (DEBUG, APPLICATION_ID, BUILD_TYPE, VERSION_CODE, FLAVOR) به‌طور خودکار ایجاد می‌شوند.

// استفاده از BuildConfig در کد
class NetworkModule {
    fun createApiClient(): ApiClient {
        return if (BuildConfig.DEBUG) {
            ApiClient(
                baseUrl = BuildConfig.API_URL,
                interceptor = HttpLoggingInterceptor()
            )
        } else {
            ApiClient(baseUrl = BuildConfig.API_URL)
        }
    }
}

BuildConfig همچنین امکان فعال یا غیرفعال کردن قابلیت‌ها را در مرحله بیلد فراهم می‌کند. مثلاً می‌توان فیلد FEATURE_CHAT_ENABLED را اضافه کرد و چت را فقط در نسخه کامل برنامه فعال کرد، بدون بررسی‌های runtime و عملگرهای شرطی در کد.

برای دیباگ درخواست‌های شبکه‌ای، BuildConfig با فیلد DEBUG امکان اتصال خودکار HttpLoggingInterceptor در OkHttp را فقط برای بیلدهای debug فراهم می‌کند. این تضمین می‌کند که در production هیچ درخواست HTTP ثبت نشود، حتی اگر توسعه‌دهنده به‌طور تصادفی فراموش کند قبل از ساخت release لاگ‌گیری را حذف کند.

Build Config در iOS: Xcode و Build Settings

در اکوسیستم iOS، Build Config از طریق Xcode Build Settings مدیریت می‌شود — جدولی از پارامترها که هر پارامتر می‌تواند برای کانفیگ‌های مختلف (Debug, Release, Staging) مقادیر متفاوتی داشته باشد.

Xcode Build Configurations

به‌طور پیش‌فرض Xcode دو کانفیگ ایجاد می‌کند: Debug (برای توسعه، بدون بهینه‌سازی) و Release (برای تولید، با بهینه‌سازی -Os). توسعه‌دهنده می‌تواند از طریق منوی Project > Info > Configurations کانفیگ‌های خود را اضافه کند.

برای هر کانفیگ، Build Settings تنظیم می‌شوند: فلگ‌های کامپایلر (OTHER_SWIFT_FLAGS, GCC_PREPROCESSOR_DEFINITIONS)، کد امضا (CODE_SIGN_IDENTITY)، پروفایل‌های provisioning و entitlements. Xcode این تنظیمات را در فایل project.pbxproj ذخیره می‌کند.

xcconfig: فایل‌های کانفیگ خارجی

برای مدیریت راحت Build Settings، توسعه‌دهندگان iOS از فایل‌های .xcconfig استفاده می‌کنند — فایل‌های متنی با پارامترهایی به فرمت KEY = VALUE. این معادل .env برای Xcode است: مقادیر به پروژه متصل می‌شوند و تنظیمات موجود در project.pbxproj را بازنویسی می‌کنند.

// Debug.xcconfig
BUNDLE_ID_SUFFIX = .debug
API_BASE_URL = http://localhost:8080
SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG
CODE_SIGN_IDENTITY = Apple Development

// Release.xcconfig
BUNDLE_ID_SUFFIX =
API_BASE_URL = https://api.production.com
SWIFT_ACTIVE_COMPILATION_CONDITIONS =
CODE_SIGN_IDENTITY = Apple Distribution

Info.plist: کانفیگ زمان اجرا

بخشی از پارامترهای Build Config وارد Info.plist می‌شود — فایل مانیفست برنامه iOS. از طریق Info.plist طرح‌های URL، مجوزها (دوربین، میکروفون)، حالت‌های پس‌زمینه و پیکربندی ورود از طریق سرویس‌های شخص ثالث تنظیم می‌شوند.

مقادیر xcconfig را می‌توان از طریق سینتکس $(VARIABLE_NAME) در Info.plist جایگذاری کرد. مثلاً $(API_BASE_URL) در Info.plist مطابق کانفیگ فعال بیلد باز می‌شود. این مدیریت پارامترهای محیطی را برای همه پلتفرم‌های Apple متمرکز می‌کند.

Build Config در پایپلاین‌های CI/CD

در پروژه‌های مدرن، Build Config با سیستم‌های یکپارچه‌سازی پیوسته یکپارچه می‌شود: GitLab CI, GitHub Actions, Bitrise, CircleCI. هر پایپلاین می‌تواند پارامترهای Build Config را از طریق متغیرهای محیطی سیستم CI/CD بازنویسی کند.

Gradle Build Config در CI

برای اندروید، پایپلاین CI Gradle را با مشخص کردن Build Variant اجرا می‌کند: ./gradlew assembleFullRelease. پارامترهای امضا از طریق متغیرهای CI منتقل می‌شوند: STORE_PASSWORD, KEY_ALIAS. Gradle آن‌ها را از محیط اجرا می‌خواند و در build.gradle.kts جایگذاری می‌کند.

// build.gradle.kts — خواندن از متغیرهای CI
android {
    signingConfigs {
        register("release") {
            storeFile = file(System.getenv("KEYSTORE_PATH") ?: "debug.keystore")
            storePassword = System.getenv("STORE_PASSWORD") ?: ""
            keyAlias = System.getenv("KEY_ALIAS") ?: "key"
            keyPassword = System.getenv("KEY_PASSWORD") ?: ""
        }
    }
}

Xcode Build Config در CI

برای iOS، CI از xcodebuild با فلگ‌های کانفیگ استفاده می‌کند: -configuration Release. گواهینامه‌های امضا از طریق secrets CI و پروفایل‌ها از طریق Apple Developer Portal API یا Fastlane match تحویل داده می‌شوند.

ابزار Fastlane مدیریت Build Config را خودکار می‌کند: xcconfig تولید می‌کند، نسخه‌ها را در Info.plist به‌روزرسانی می‌کند، فایل‌های IPA ساخته‌شده را امضا می‌کند و آن‌ها را در App Store Connect آپلود می‌کند. Fastlane gym (ساخت) و match (امضا) — استاندارد پایپلاین‌های CI iOS است.

طبق Bitrise Build Report (2025)، پروژه‌هایی که Build Config را در CI پیکربندی کرده‌اند، زمان پیکربندی دستی بیلد را 73% کاهش می‌دهند و تعداد خطاهای امضا را 89% کاهش می‌دهند. Build Config خودکار — عنصر الزامی پایپلاین production-ready است.

جنبه مهم دیگر — پارامتریسازی نسخه‌بندی از طریق Build Config است. Gradle امکان خواندن versionCode و versionName از متغیرهای CI و جایگذاری پویای آن‌ها در build.gradle.kts را فراهم می‌کند، که ناهماهنگی نسخه‌ها بین توسعه‌دهندگان را از بین می‌برد. در iOS کار مشابه از طریق agvtool (Apple Generic Versioning Tool) حل می‌شود که می‌تواند شماره بیلد را بر اساس تگ‌های git یا شماره بیلد در CI افزایش دهد.