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 มีแพลตฟอร์มของตัวเอง: 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 (ตัวอย่างนักพัฒนา) compileSdkPreview ใช้สำหรับทดสอบระดับ API ที่กำลังจะมาถึงก่อนการเผยแพร่อย่างเป็นทางการ

// build.gradle.kts — การกำหนดค่า compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — ระดับ API เสถียรล่าสุด (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 ที่ไม่เสถียรก่อนการเผยแพร่แพลตฟอร์มอย่างเป็นทางการ หลังจากการเผยแพร่ ตัวอย่างจะถูกแทนที่ด้วย compileSdk = 36 ที่เสถียร

compileSdkVersion vs targetSdkVersion vs minSdkVersion

พารามิเตอร์ระดับ API สามตัว ใน build.gradle — compileSdkVersion, targetSdkVersion และ minSdkVersion — มักสับสน แต่ละตัวรับผิดชอบด้านความเข้ากันได้ที่แตกต่างกัน และค่าของมันต้องปฏิบัติตามกฎ compileSdk >= targetSdk >= minSdk minSdk คือขอบเขตล่าง: อุปกรณ์ที่ต่ำกว่านี้จะไม่เห็นแอป targetSdk คือจุดทดสอบ: การเปลี่ยนแปลงพฤติกรรมจะเปิดใช้งานจนถึงระดับนี้ compileSdk คือเพดาน: API ที่สูงกว่าระดับนี้จะไม่พร้อมใช้งานสำหรับคอมไพเลอร์

กฎปฏิบัติที่สำคัญ: compileSdk สามารถเพิ่มได้โดยไม่ต้องทดสอบบนอุปกรณ์ใด ๆ นี่เป็นการดำเนินการที่ปลอดภัยซึ่งเพียงแค่ให้คอมไพเลอร์มี android.jar เวอร์ชันใหม่ ความเสี่ยงเดียวคือ API ที่เลิกใช้แล้วซึ่งอาจถูกลบออกในเวอร์ชันแพลตฟอร์มใหม่ แต่จะตรวจพบในเวลาคอมไพล์และแก้ไขได้ง่าย ในทางกลับกัน การเพิ่ม targetSdk ต้องใช้วงจร QA เต็มรูปแบบ

ทำไม compileSdk ถึงสูงกว่า targetSdk ได้? ลองนึกภาพว่า Android 16 (API 36) เปิดตัวพร้อม API ใหม่ที่คุณต้องการใช้ในโค้ด แต่คุณยังไม่ได้ทดสอบการเปลี่ยนแปลงพฤติกรรมของ API 36 คุณตั้งค่า compileSdk = 36 (API ใหม่พร้อมใช้งาน), targetSdk = 35 (ปิดการเปลี่ยนแปลงพฤติกรรมของ API 36) โค้ดจะคอมไพล์ ใช้เมธอดใหม่ภายใต้การตรวจสอบ SDK_INT และการเปลี่ยนแปลงพฤติกรรมของ API 36 จะไม่ทำให้แอปเสียหายเพราะ targetSdk = 35

ตัวอย่างชุดค่าผสมที่ถูกต้อง

compileSdk = 36, targetSdk = 36, minSdk = 26 — ความเข้ากันได้เต็มรูปแบบกับ API และการเปลี่ยนแปลงพฤติกรรมล่าสุด ครอบคลุม 85% ของอุปกรณ์ compileSdk = 36, targetSdk = 34, minSdk = 26 — API ใหม่พร้อมใช้งาน การเปลี่ยนแปลงพฤติกรรมเฉพาะถึง API 34 compileSdk = 35, targetSdk = 36 — ไม่ถูกต้อง: compileSdk ต่ำกว่า targetSdk, API 36 ไม่พร้อมใช้งานในขณะที่การเปลี่ยนแปลงพฤติกรรมของ 36 เปิดใช้งานอยู่

วิธีอัปเดต compileSdkVersion: คำแนะนำทีละขั้นตอน

การอัปเดต compileSdkVersion เป็นหนึ่งในการดำเนินการที่ง่ายและปลอดภัยที่สุดในโปรเจกต์ Android ต่างจาก targetSdk ตรงที่ไม่ต้องทดสอบการเปลี่ยนแปลงพฤติกรรมอย่างละเอียด อย่างไรก็ตาม มีบางขั้นตอนที่ต้องปฏิบัติตามเพื่อหลีกเลี่ยงข้อผิดพลาดในการคอมไพล์และคำเตือนเกี่ยวกับการเลิกใช้

ขั้นตอนที่ 1 — ติดตั้งแพลตฟอร์มใหม่ ผ่าน SDK Manager ใน Android Studio: Tools → SDK Manager → SDK Platforms → เลือกระดับ API ใหม่ หากคุณไม่ได้ติดตั้งแพลตฟอร์ม Gradle จะพยายามดาวน์โหลดโดยอัตโนมัติ แต่อาจทำให้การสร้างครั้งแรกช้าลง ขั้นตอนที่ 2 — เปลี่ยน compileSdk ใน build.gradle เป็นค่าใหม่ ขั้นตอนที่ 3 — สร้าง (Build → Make Project) และแก้ไขข้อผิดพลาดในการคอมไพล์

ขั้นตอนที่ 4 — ตรวจสอบ API ที่เลิกใช้แล้ว หลังจากอัปเกรด compileSdk เมธอดบางตัวอาจถูกทำเครื่องหมาย @Deprecated พร้อมหมายเหตุ "removed in API X" Android Studio จะไฮไลต์ด้วยการขีดฆ่าและแสดงคำเตือน แทนที่การเรียกที่เลิกใช้แล้วด้วยทางเลือกใหม่ หากทางเลือกต้องการระดับ API สูงกว่า minSdk ให้เพิ่มการตรวจสอบขณะรันไทม์ ขั้นตอนที่ 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 สำหรับอุปกรณ์เก่า จะใช้ทางเลือกสำรองกับ @Suppress("DEPRECATION")

การทำงานกับ API ใหม่: การตรวจสอบแบบมีเงื่อนไขและทางเลือกสำรอง

API ใหม่ ที่พร้อมใช้งานจากการอัปเกรด compileSdkVersion ไม่สามารถเรียกได้โดยตรงหาก minSdkVersion ต่ำกว่าระดับ API นั้น หากไม่มีการตรวจสอบขณะรันไทม์ แอปจะล้มเหลวด้วย AbstractMethodError, NoSuchMethodError หรือ VerifyError บนอุปกรณ์เก่า กลไกป้องกันหลักคือการตรวจสอบ Build.VERSION.SDK_INT เรียก API ใหม่เฉพาะเมื่อระดับ API เพียงพอ และมีทางเลือกสำรองสำหรับเวอร์ชันเก่า

AndroidX มีการย้อนกลับสำหรับ 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)
        }
        // ทางเลือกสำรอง: การจัดรูปแบบด้วยตนเองสำหรับ API เก่า
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: ไม่ต้องย้อนกลับ — การตรวจสอบ 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 สมมติ) ด้วยการจัดรูปแบบสำรองสำหรับเวอร์ชันเก่า หลักการสำคัญ: compileSdk ให้สิทธิ์เข้าถึงการเรียกเมธอดใหม่ในโค้ด แต่การตรวจสอบ 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 จะส่งผลต่อระดับ API ขั้นต่ำสำหรับโค้ดเนทีฟผ่าน APP_MIN_SDK_VERSION ใน Application.mk

Gradle (7.6+) และ Kotlin (2.0+) ก็ส่งผลต่อความเข้ากันได้ของ compileSdk เช่นกัน AGP 8.7+ ต้องการ Gradle 8.9+ และ Kotlin 2.0+ เมื่ออัปเกรด compileSdk แนะนำให้อัปเดต AGP, Gradle และ Kotlin เป็นเวอร์ชันเสถียรล่าสุด ตรวจสอบความเข้ากันได้ในตารางความเข้ากันได้ของ Android Gradle Plugin อย่างเป็นทางการ

ปัญหาทั่วไปเมื่ออัปเกรด compileSdk

ปัญหาเมื่ออัปเกรด compileSdkVersion แบ่งออกเป็นสามประเภท: ข้อผิดพลาดในการคอมไพล์ คำเตือนเกี่ยวกับการเลิกใช้ และความไม่เข้ากันขณะรันไทม์ ข้อผิดพลาดในการคอมไพล์ — เมธอดถูกลบออกจาก API และโค้ดไม่คอมไพล์ คำเตือนเกี่ยวกับการเลิกใช้ — เมธอดถูกทำเครื่องหมาย @Deprecated โค้ดคอมไพล์พร้อมคำเตือน ความไม่เข้ากันขณะรันไทม์ — API ใหม่จำเป็นสำหรับฟังก์ชันบางอย่างและทำให้เกิดข้อผิดพลาดหากระดับ API บนอุปกรณ์ไม่เพียงพอ

ปัญหาทั่วไปแรก — "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") พร้อมคำอธิบายเหตุผลที่เก็บไว้