compileSdkVersion: مبانی، APIهای جدید و تنظیمات در Gradle

compileSdkVersion در Android چیست؟

compileSdkVersion — یک پارامتر عددی در build.gradle است که مشخص می‌کند کد در مقابل کدام نسخه از Android SDK کامپایل شود. وقتی کدی می‌نویسید که از کلاس‌های android.* یا androidx.* استفاده می‌کند، کامپایلر آنها را با APIهای موجود در نسخه مشخص شده compileSdk بررسی می‌کند. اگر متدی در API 36 ظاهر شده باشد و compileSdk = 35 باشد، کد کامپایل نمی‌شود. اگر compileSdk = 36 باشد — کد کامپایل می‌شود، اما در دستگاهی با API 35 هنگام فراخوانی این متد بدون بررسی، خطا رخ می‌دهد.

compileSdkVersion از Android SDK Platform نصب شده از طریق SDK Manager در Android Studio بارگیری می‌شود. هر API Level پلتفرم خود را دارد: android-21, android-29, android-34, android-35, android-36. پلتفرم شامل android.jar — مجموعه‌ای از کلاس‌ها، متدها و ثابت‌هایی است که کامپایلر Kotlin/Java با آنها کار می‌کند. اگر پلتفرم نصب نباشد، Gradle آن را به صورت خودکار از طریق sdkmanager در اولین ساخت بارگیری می‌کند.

AGP (Android Gradle Plugin) نسخه 8.7+ توصیه می‌کند compileSdk را به صورت یک عدد کامل از طریق compileSdk = 36 در Kotlin DSL و بدون پیشوند android- مشخص کنید. compileSdk را می‌توان همچنین از طریق compileSdkVersion 36 در Groovy DSL یا compileSdkPreview برای نسخه‌های پیش‌نمایش SDK (developer previews) مشخص کرد. compileSdkPreview برای测试 API Level آینده قبل از انتشار رسمی استفاده می‌شود.

// build.gradle.kts — تنظیمات compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — آخرین API Level پایدار (Android 16)
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36
        versionCode = 1
        versionName = "1.0.0"
    }
}

// به طور جایگزین: compileSdkPreview برای نسخه‌های پیش‌نمایش
// compileSdkPreview = "Baklava"

در مثال compileSdk = 36 دسترسی به تمام APIهای Android 16 (Baklava) را فراهم می‌کند. Android SDK Platform 36 باید در SDK Manager نصب شود. compileSdkPreview با نام "Baklava" را می‌توان برای تست APIهای ناپایدار قبل از انتشار رسمی پلتفرم استفاده کرد. پس از انتشار، preview با compileSdk = 36 پایدار جایگزین می‌شود.

compileSdkVersion در مقابل targetSdkVersion در مقابل minSdkVersion

سه پارامتر API Level در build.gradle — compileSdkVersion, targetSdkVersion و minSdkVersion — اغلب اشتباه گرفته می‌شوند. هر یک مسئول جنبه متفاوتی از سازگاری است و مقادیر آنها باید طبق قانون compileSdk >= targetSdk >= minSdk هماهنگ شوند. minSdk — حد پایین: دستگاه‌های پایین‌تر برنامه را نخواهند دید. targetSdk — نقطه تست: behavioural changes تا این سطح فعال می‌شوند. compileSdk — سقف: APIهای بالاتر از این سطح برای کامپایلر در دسترس نیستند.

قانون عملی کلیدی: compileSdk را می‌توان بدون هیچ تستی روی دستگاه‌ها افزایش داد. این یک عملیات ایمن است که فقط یک نسخه جدید از android.jar در اختیار کامپایلر قرار می‌دهد. تنها ریسک — APIهای منسوخ که ممکن است در نسخه جدید پلتفرم حذف شوند، اما این در مرحله کامپایل تشخیص داده می‌شود و به راحتی قابل رفع است. افزایش targetSdk، برعکس، نیاز به چرخه کامل QA دارد.

چرا compileSdk می‌تواند بالاتر از targetSdk باشد؟ تصور کنید Android 16 (API 36) با APIهای جدیدی منتشر شده که می‌خواهید در کد استفاده کنید، اما behavioural changes API 36 را هنوز تست نکرده‌اید. شما compileSdk = 36 (APIهای جدید در دسترس)، targetSdk = 35 (behavioural changes API 36 غیرفعال) تنظیم می‌کنید. کد کامپایل می‌شود، از متدهای جدید تحت بررسی‌های SDK_INT استفاده می‌کند و behavioural changes API 36 برنامه را خراب نمی‌کند، زیرا targetSdk = 35 است.

نمونه‌هایی از ترکیبات صحیح

compileSdk = 36, targetSdk = 36, minSdk = 26 — سازگاری کامل با آخرین APIها و behavioural changes، پوشش 85٪ دستگاه‌ها. compileSdk = 36, targetSdk = 34, minSdk = 26 — APIهای جدید در دسترس، behavioural changes فقط تا API 34. compileSdk = 35, targetSdk = 36 — نادرست: compileSdk پایین‌تر از targetSdk، API 36 در دسترس نیست، در حالی که behavioural changes 36 فعال هستند.

نحوه به‌روزرسانی compileSdkVersion: راهنمای گام به گام

به‌روزرسانی compileSdkVersion — یکی از ساده‌ترین و ایمن‌ترین عملیات در پروژه Android است. برخلاف targetSdk، نیاز به تست طولانی behavioural changes ندارد. با این حال چند مرحله وجود دارد که باید انجام شود تا از خطاهای کامپایل و هشدارهای منسوخ جلوگیری شود.

مرحله 1 — پلتفرم جدید را نصب کنید از طریق SDK Manager در Android Studio: Tools → SDK Manager → SDK Platforms → API Level جدید را انتخاب کنید. اگر پلتفرم را نصب نکنید، Gradle سعی می‌کند آن را به صورت خودکار بارگیری کند، اما این ممکن است اولین ساخت را کند کند. مرحله 2 — compileSdk را در build.gradle به مقدار جدید تغییر دهید. مرحله 3 — ساخت را انجام دهید (Build → Make Project) و خطاهای کامپایل را رفع کنید.

مرحله 4 — APIهای منسوخ را بررسی کنید. پس از افزایش compileSdk، برخی متدها ممکن است با @Deprecated و یادداشت "removed in API X" مشخص شوند. Android Studio آنها را با خط زدن برجسته می‌کند و هشدار می‌دهد. فراخوانی‌های منسوخ را با جایگزین‌های جدید تعویض کنید. اگر جایگزین به API Level بالاتر از minSdk نیاز دارد، بررسی runtime اضافه کنید. مرحله 5 — dependencies را بررسی کنید: برخی کتابخانه‌ها ممکن است به نسخه خاصی از compileSdk نیاز داشته باشند. AGP 8.7+ compileSdk = 36 را توصیه می‌کند.

// پس از افزایش compileSdk: جایگزینی APIهای منسوخ
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // قبل: متد منسوخ (ممکن است در API جدید حذف شود)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // ممکن است در API 36 منسوخ شود
    }

    // بعد: جایگزین جدید (در صورت وجود)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // API جدید از compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // نمونه API جدید
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

کلاس CompileSdkMigration الگوی صحیح مهاجرت را نشان می‌دهد. متد قدیمی memoryClass ممکن است در API جدید حذف شود — کامپایلر خطا می‌دهد. جایگزین جدید getMemoryClassSafe فقط در API 36+ در دسترس است، بنابراین تحت بررسی SDK_INT >= BAKLAVA فراخوانی می‌شود. برای دستگاه‌های قدیمی از fallback با @Suppress("DEPRECATION") استفاده می‌شود.

کار با APIهای جدید: بررسی‌های شرطی و fallback

APIهای جدید که به لطف افزایش compileSdkVersion در دسترس قرار می‌گیرند، در صورتی که minSdkVersion پایین‌تر از این API Level باشد، نمی‌توان مستقیماً فراخوانی کرد. بدون بررسی runtime، برنامه در دستگاه‌های قدیمی با AbstractMethodError، NoSuchMethodError یا VerifyError خراب می‌شود. مکانیسم حفاظتی اصلی — بررسی Build.VERSION.SDK_INT با فراخوانی API جدید فقط در API Level کافی و fallback برای نسخه‌های قدیمی.

AndroidX backportهای بسیاری از APIهای جدید را فراهم می‌کند که امکان استفاده از متدهای مدرن را حتی با compileSdk پایین فراهم می‌کند. به عنوان مثال، Activity Result API از androidx.activity:activity-ktx:1.9.3 در تمام نسخه‌های Android از API 14 به بعد کار می‌کند. NotificationCompat از AndroidX امکان استفاده از اعلان‌های مدرن در APIهای قدیمی را فراهم می‌کند. PhotoPicker از طریق ActivityResultContracts.PickVisualMedia از API 34+ در دسترس است.

// فراخوانی ایمن API جدید با compileSdk 36 و minSdk 26
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: متد جدید کار با رنگ
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // API جدید از compileSdk 36 — نیاز به API 36+ دارد
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: قالب‌بندی دستی برای APIهای قدیمی
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: backport لازم نیست — بررسی SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// استفاده در Activity
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

کلاس NewApiHelper فراخوانی ایمن API جدید Color.toArgbHexString (API 36 فرضی) با fallback-فرمت‌بندی برای نسخه‌های قدیمی را نشان می‌دهد. اصل کلیدی: compileSdk دسترسی به فراخوانی متدهای جدید در کد را فراهم می‌کند، اما بررسی runtime SDK_INT از خرابی در دستگاه‌های قدیمی محافظت می‌کند. بدون بررسی SDK_INT، برنامه با minSdk 26 و compileSdk 36 در Android 8-15 خراب می‌شود.

AGP (Android Gradle Plugin) و compileSdkVersion

Android Gradle Plugin (AGP) — ابزار اصلی ساخت برنامه‌های Android است. هر نسخه AGP محدوده خاصی از compileSdkVersion را پشتیبانی می‌کند. AGP 8.7.x (منتشر شده در سال 2026) نیاز به compileSdk >= 34 دارد و compileSdk = 36 را توصیه می‌کند. AGP 8.5.x از compileSdk 33-35 پشتیبانی می‌کند. اگر compileSdk پایین‌تر از حداقل مورد نیاز AGP باشد، ساخت با خطای "The SDK platform (X) is not supported by this version of the Android Gradle Plugin" پایان می‌یابد.

NDK (Native Development Kit) نیز به compileSdkVersion وابسته است. اگر پروژه از کد بومی C/C++ از طریق NDK استفاده می‌کند، compileSdk نسخه فایل‌های هدر و کتابخانه‌ها را تعیین می‌کند. NDK r27+ compileSdk 36 را توصیه می‌کند. برای کتابخانه‌های با فایل‌های .so، compileSdk از طریق APP_MIN_SDK_VERSION در Application.mk بر حداقل API Level برای کد بومی تأثیر می‌گذارد.

Gradle (7.6+) و Kotlin (2.0+) نیز بر سازگاری با compileSdk تأثیر می‌گذارند. AGP 8.7+ نیاز به Gradle 8.9+ و Kotlin 2.0+ دارد. هنگام افزایش compileSdk توصیه می‌شود AGP، Gradle و Kotlin را به آخرین نسخه‌های پایدار به‌روزرسانی کنید. سازگاری را در جدول رسمی Android Gradle Plugin Compatibility بررسی کنید.

مشکلات رایج در افزایش compileSdk

مشکلات در افزایش compileSdkVersion به سه دسته تقسیم می‌شوند: compilation errors، deprecated warnings و runtime incompatibilities. Compilation errors — متدها از API حذف شده‌اند و کد کامپایل نمی‌شود. Deprecated warnings — متدها با @Deprecated مشخص شده‌اند، کد با هشدار کامپایل می‌شود. Runtime incompatibilities — APIهای جدید برای عملکرد خاصی اجباری هستند و در صورت API Level ناکافی روی دستگاه باعث خطا می‌شوند.

اولین مشکل رایج — "Cannot resolve symbol X". این به این معنی است که کلاس یا متد از API عمومی در نسخه جدید SDK حذف شده است. راه حل: پیدا کردن جایگزین در پلتفرم جدید یا استفاده از معادل AndroidX. به عنوان مثال، کلاس AsyncTaskLoader در API 28 منسوخ و از API عمومی در نسخه‌های جدیدتر حذف شده است. جایگزین — Kotlin Coroutines یا WorkManager.

دومین مشکل — تغییر امضای متد. در نسخه جدید API، متد ممکن است تعداد یا نوع پارامترها را تغییر دهد. کامپایلر Kotlin/Java خطای "None of the following functions can be called with the arguments supplied" می‌دهد. راه حل: فراخوانی متد را با امضای جدید به‌روزرسانی کنید یا با بررسی SDK_INT امضای قدیمی را برای دستگاه‌های قدیمی فراخوانی کنید.

// حل مشکلات در افزایش compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // مشکل: متد hasSystemFeature امضا را در API 36 تغییر داد
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // امضای جدید: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // امضای قدیمی: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // مشکل: کلاس حذف شده، از معادل AndroidX استفاده می‌کنیم
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // به جای android.app.FragmentManager (حذف شده) استفاده می‌کنیم
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

کلاس CompileSdkProblemFixer مشکلات رایج را حل می‌کند: امضای تغییر یافته hasSystemFeature (تغییر فرضی در API 36) از طریق بررسی SDK_INT با فراخوانی نسخه صحیح متد مدیریت می‌شود. کلاس حذف شده android.app.FragmentManager با معادل AndroidX جایگزین شده است. برای فراخوانی‌های قدیمی که جایگزینی ندارند، از @Suppress("DEPRECATION") با توضیح دلیل نگهداری استفاده می‌شود.