compileSdkVersion: kiến thức cơ bản, API mới và cấu hình trong Gradle

compileSdkVersion trong Android là gì?

compileSdkVersion là một tham số số nguyên trong build.gradle chỉ định phiên bản Android SDK để biên dịch mã. Khi bạn viết mã sử dụng các lớp từ android.* hoặc androidx.*, trình biên dịch sẽ đối chiếu chúng với các API có sẵn trong phiên bản compileSdk đã chỉ định. Nếu một phương thức được giới thiệu trong API 36 và compileSdk = 35, mã sẽ không biên dịch được. Nếu compileSdk = 36, mã sẽ biên dịch được, nhưng gọi phương thức đó trên thiết bị có API 35 mà không kiểm tra sẽ gây ra sự cố.

compileSdkVersion được tải từ Nền tảng Android SDK được cài đặt qua SDK Manager trong Android Studio. Mỗi Cấp độ API có nền tảng riêng: android-21, android-29, android-34, android-35, android-36. Nền tảng chứa android.jar — một tập hợp các lớp, phương thức và hằng số mà trình biên dịch Kotlin/Java sử dụng. Nếu nền tảng chưa được cài đặt, Gradle sẽ tự động tải xuống qua sdkmanager trong lần xây dựng đầu tiên.

AGP (Android Gradle Plugin) phiên bản 8.7+ khuyến nghị chỉ định compileSdk dưới dạng số nguyên qua compileSdk = 36 trong Kotlin DSL, không có tiền tố android-. compileSdk cũng có thể được đặt qua compileSdkVersion 36 trong Groovy DSL hoặc compileSdkPreview cho các phiên bản SDK trước phát hành (bản xem trước dành cho nhà phát triển). compileSdkPreview được sử dụng để kiểm tra các Cấp độ API sắp tới trước khi phát hành chính thức.

// build.gradle.kts — cấu hình compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — Cấp độ API ổn định mới nhất (Android 16)
    compileSdk = 36

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

// Thay thế: compileSdkPreview cho phiên bản xem trước
// compileSdkPreview = "Baklava"

Trong ví dụ, compileSdk = 36 cung cấp quyền truy cập vào tất cả API của Android 16 (Baklava). Nền tảng Android SDK 36 phải được cài đặt trong SDK Manager. compileSdkPreview với tên "Baklava" có thể được sử dụng để kiểm tra API không ổn định trước khi phát hành nền tảng chính thức. Sau khi phát hành, bản xem trước được thay thế bằng compileSdk = 36 ổn định.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Ba tham số Cấp độ API trong build.gradle — compileSdkVersion, targetSdkVersion và minSdkVersion — thường bị nhầm lẫn. Mỗi tham số chịu trách nhiệm cho một khía cạnh khác nhau của tính tương thích và giá trị của chúng phải tuân theo quy tắc compileSdk >= targetSdk >= minSdk. minSdk là giới hạn dưới: các thiết bị thấp hơn sẽ không thấy ứng dụng. targetSdk là điểm kiểm tra: các thay đổi hành vi được kích hoạt đến cấp độ này. compileSdk là trần: các API trên cấp độ này không khả dụng cho trình biên dịch.

Quy tắc thực hành chính: compileSdk có thể được tăng mà không cần bất kỳ kiểm tra nào trên thiết bị. Đây là một thao tác an toàn chỉ đơn giản cung cấp cho trình biên dịch một phiên bản mới của android.jar. Rủi ro duy nhất là các API không dùng nữa có thể bị xóa trong phiên bản nền tảng mới, nhưng điều này được phát hiện tại thời điểm biên dịch và dễ dàng sửa. Ngược lại, tăng targetSdk đòi hỏi một chu kỳ QA đầy đủ.

Tại sao compileSdk có thể cao hơn targetSdk? Hãy tưởng tượng Android 16 (API 36) được phát hành với các API mới bạn muốn sử dụng trong mã, nhưng bạn chưa kiểm tra các thay đổi hành vi của API 36. Bạn đặt compileSdk = 36 (API mới có sẵn), targetSdk = 35 (thay đổi hành vi API 36 bị vô hiệu hóa). Mã sẽ biên dịch, sử dụng các phương thức mới dưới sự kiểm tra SDK_INT và các thay đổi hành vi của API 36 sẽ không làm hỏng ứng dụng vì targetSdk = 35.

Ví dụ về các kết hợp đúng

compileSdk = 36, targetSdk = 36, minSdk = 26 — tương thích hoàn toàn với các API và thay đổi hành vi mới nhất, bao phủ 85% thiết bị. compileSdk = 36, targetSdk = 34, minSdk = 26 — API mới có sẵn, thay đổi hành vi chỉ đến API 34. compileSdk = 35, targetSdk = 36 — không đúng: compileSdk thấp hơn targetSdk, API 36 không khả dụng trong khi thay đổi hành vi của 36 đang hoạt động.

Cách cập nhật compileSdkVersion: hướng dẫn từng bước

Cập nhật compileSdkVersion là một trong những thao tác đơn giản và an toàn nhất trong dự án Android. Không giống như targetSdk, nó không yêu cầu kiểm tra rộng rãi các thay đổi hành vi. Tuy nhiên, có một số bước cần tuân theo để tránh lỗi biên dịch và cảnh báo không dùng nữa.

Bước 1 — cài đặt nền tảng mới qua SDK Manager trong Android Studio: Tools → SDK Manager → SDK Platforms → chọn Cấp độ API mới. Nếu bạn không cài đặt nền tảng, Gradle sẽ cố gắng tải xuống tự động, nhưng điều này có thể làm chậm lần xây dựng đầu tiên. Bước 2 — thay đổi compileSdk trong build.gradle thành giá trị mới. Bước 3 — xây dựng (Build → Make Project) và sửa bất kỳ lỗi biên dịch nào.

Bước 4 — kiểm tra API không dùng nữa. Sau khi nâng cấp compileSdk, một số phương thức có thể được đánh dấu @Deprecated với ghi chú "removed in API X". Android Studio đánh dấu chúng bằng gạch ngang và hiển thị cảnh báo. Thay thế các lệnh gọi không dùng nữa bằng các lựa chọn thay thế mới. Nếu lựa chọn thay thế yêu cầu Cấp độ API cao hơn minSdk, hãy thêm kiểm tra runtime. Bước 5 — kiểm tra phụ thuộc: một số thư viện có thể yêu cầu phiên bản compileSdk cụ thể. AGP 8.7+ khuyến nghị compileSdk = 36.

// Sau khi nâng cấp compileSdk: thay thế API không dùng nữa
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 {

    // TRƯỚC: phương thức không dùng nữa (có thể bị xóa trong API mới)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Có thể không dùng nữa trong API 36
    }

    // SAU: lựa chọn thay thế mới (nếu có)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // API mới từ compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Ví dụ về API mới
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

Lớp CompileSdkMigration minh họa mô hình di chuyển chính xác. Phương thức cũ memoryClass có thể bị xóa trong API mới — trình biên dịch sẽ báo lỗi. Lựa chọn thay thế mới getMemoryClassSafe chỉ khả dụng trên API 36+, vì vậy nó được gọi dưới kiểm tra SDK_INT >= BAKLAVA. Đối với các thiết bị cũ, một phương án dự phòng với @Suppress("DEPRECATION") được sử dụng.

Làm việc với API mới: kiểm tra có điều kiện và dự phòng

Các API mới có được nhờ nâng cấp compileSdkVersion không thể được gọi trực tiếp nếu minSdkVersion thấp hơn Cấp độ API đó. Nếu không có kiểm tra runtime, ứng dụng sẽ gặp sự cố với AbstractMethodError, NoSuchMethodError hoặc VerifyError trên các thiết bị cũ. Cơ chế bảo vệ chính là kiểm tra Build.VERSION.SDK_INT, chỉ gọi API mới khi Cấp độ API đủ cao và cung cấp phương án dự phòng cho các phiên bản cũ.

AndroidX cung cấp các bản port ngược cho nhiều API mới, cho phép sử dụng các phương thức hiện đại ngay cả với compileSdk thấp. Ví dụ, API Activity Result từ androidx.activity:activity-ktx:1.9.3 hoạt động trên tất cả các phiên bản Android từ API 14. NotificationCompat từ AndroidX cho phép thông báo hiện đại trên các API cũ. PhotoPicker có sẵn qua ActivityResultContracts.PickVisualMedia từ API 34+.

// Gọi an toàn API mới với compileSdk 36 và 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+: phương thức mới để làm việc với màu sắc
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // API mới từ compileSdk 36 — yêu cầu API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Dự phòng: định dạng thủ công cho API cũ
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: không cần port ngược — kiểm tra SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Sử dụng trong 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")
    }
}

Lớp NewApiHelper minh họa cách gọi an toàn API mới Color.toArgbHexString (API 36 giả định) với định dạng dự phòng cho các phiên bản cũ. Nguyên tắc chính: compileSdk cung cấp quyền truy cập để gọi các phương thức mới trong mã, nhưng kiểm tra SDK_INT runtime bảo vệ khỏi sự cố trên các thiết bị cũ. Nếu không có kiểm tra SDK_INT, ứng dụng với minSdk 26 và compileSdk 36 sẽ gặp sự cố trên Android 8-15.

AGP (Android Gradle Plugin) và compileSdkVersion

Android Gradle Plugin (AGP) là công cụ xây dựng chính cho các ứng dụng Android. Mỗi phiên bản AGP hỗ trợ một phạm vi compileSdkVersion cụ thể. AGP 8.7.x (phát hành năm 2026) yêu cầu compileSdk >= 34 và khuyến nghị compileSdk = 36. AGP 8.5.x hỗ trợ compileSdk 33-35. Nếu compileSdk thấp hơn mức tối thiểu cho AGP, quá trình xây dựng sẽ thất bại với lỗi: "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) cũng được liên kết với compileSdkVersion. Nếu dự án của bạn sử dụng mã gốc C/C++ qua NDK, compileSdk xác định phiên bản của tệp tiêu đề và thư viện. NDK r27+ khuyến nghị compileSdk 36. Đối với các thư viện có tệp .so, compileSdk ảnh hưởng đến Cấp độ API tối thiểu cho mã gốc qua APP_MIN_SDK_VERSION trong Application.mk.

Gradle (7.6+) và Kotlin (2.0+) cũng ảnh hưởng đến tính tương thích của compileSdk. AGP 8.7+ yêu cầu Gradle 8.9+ và Kotlin 2.0+. Khi nâng cấp compileSdk, khuyến nghị cập nhật AGP, Gradle và Kotlin lên các phiên bản ổn định mới nhất. Kiểm tra tính tương thích trong bảng tương thích Android Gradle Plugin chính thức.

Các vấn đề thường gặp khi nâng cấp compileSdk

Các vấn đề khi nâng cấp compileSdkVersion được chia thành ba loại: lỗi biên dịch, cảnh báo không dùng nữa và không tương thích runtime. Lỗi biên dịch — các phương thức bị xóa khỏi API và mã không biên dịch được. Cảnh báo không dùng nữa — các phương thức được đánh dấu @Deprecated, mã biên dịch với cảnh báo. Không tương thích runtime — các API mới cần thiết cho một chức năng nhất định và gây ra lỗi nếu Cấp độ API trên thiết bị không đủ.

Vấn đề phổ biến đầu tiên — "Cannot resolve symbol X". Điều này có nghĩa là một lớp hoặc phương thức đã bị xóa khỏi API công khai trong phiên bản SDK mới. Giải pháp: tìm một lựa chọn thay thế trong nền tảng mới hoặc sử dụng tương đương AndroidX. Ví dụ, lớp AsyncTaskLoader đã không dùng nữa trong API 28 và bị xóa khỏi API công khai trong các phiên bản mới hơn. Các lựa chọn thay thế bao gồm Kotlin Coroutines hoặc WorkManager.

Vấn đề thứ hai — thay đổi chữ ký phương thức. Trong phiên bản API mới, một phương thức có thể thay đổi số lượng hoặc loại tham số của nó. Trình biên dịch Kotlin/Java báo lỗi: "None of the following functions can be called with the arguments supplied". Giải pháp: cập nhật lệnh gọi phương thức để khớp với chữ ký mới hoặc thêm kiểm tra SDK_INT với lệnh gọi chữ ký cũ cho các thiết bị cũ.

// Giải quyết vấn đề khi nâng cấp compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Vấn đề: phương thức hasSystemFeature đã thay đổi chữ ký trong API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Chữ ký mới: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Chữ ký cũ: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Vấn đề: lớp bị xóa, sử dụng tương đương AndroidX
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Thay vì android.app.FragmentManager (đã xóa) sử dụng
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

Lớp CompileSdkProblemFixer giải quyết các vấn đề phổ biến: chữ ký thay đổi của hasSystemFeature (thay đổi giả định trong API 36) được xử lý qua kiểm tra SDK_INT gọi đúng phiên bản của phương thức. Lớp bị xóa android.app.FragmentManager được thay thế bằng tương đương AndroidX. Đối với các lệnh gọi cũ không có lựa chọn thay thế, @Suppress("DEPRECATION") được sử dụng với chú thích giải thích lý do giữ lại.