minSdkVersion: nó là gì và cách chọn phiên bản Android tối thiểu

minSdkVersion trong Android là gì?

minSdkVersion là một tham số số nguyên trong build.gradle chỉ định cấp API Android tối thiểu để cài đặt ứng dụng. Nếu cấp API của thiết bị thấp hơn giá trị được chỉ định, PackageManager chặn cài đặt và Google Play Store ẩn ứng dụng khỏi kết quả tìm kiếm cho thiết bị đó. minSdkVersion được ghi vào AndroidManifest.xml tại thời điểm xây dựng thông qua thẻ <uses-sdk android:minSdkVersion> và được kiểm tra ở mỗi lần cài đặt.

Giá trị minSdkVersion là sự đánh đổi giữa phạm vi tiếp cận khán giả và quyền truy cập vào các API mới. minSdk càng thấp, càng nhiều thiết bị có thể cài đặt ứng dụng, đặc biệt ở các khu vực đang phát triển nơi điện thoại thông minh Android cũ phổ biến. minSdk càng cao, càng ít mã tương thích ngược cần thiết và càng nhiều API hiện đại khả dụng mà không cần kiểm tra thời gian chạy. Android Jetpack và các thư viện AndroidX cung cấp backport của nhiều API mới cho các phiên bản Android cũ, cho phép chọn minSdk thấp hơn mà không mất chức năng.

minSdkVersion ảnh hưởng đến tất cả các giai đoạn phát triển: phân tích tĩnh (lint sử dụng minSdk để cảnh báo), tương thích phụ thuộc (thư viện có thể yêu cầu minSdk riêng), kiểm thử (cần kiểm thử trên thiết bị có minSdk) và Google Play Console (phạm vi tiếp cận khán giả được tính dựa trên minSdk). Thay đổi minSdkVersion là một trong những quyết định quan trọng nhất trong thiết lập dự án, vì nó ảnh hưởng đến mã, kiểm thử và cơ sở người dùng.

Nơi chỉ định minSdkVersion

Build.gradle.kts (Kotlin DSL) là tiêu chuẩn hiện đại trong các dự án Android. Tham số minSdk được đặt trong khối defaultConfig ở cấp mô-đun. Giá trị có thể được ghi đè cho các loại bản dựng và hương vị sản phẩm khác nhau, cho phép kiểm thử trên các API thấp hơn mà không thay đổi giá trị chính.

// build.gradle.kts — cấu hình minSdk cơ bản
android {
    namespace = "com.example.myapp"
    compileSdk = 36

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

    // Ghi đè minSdk cho các hương vị khác nhau
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

Trong ví dụ, minSdk = 26 tương ứng với Android 8.0 Oreo. Đây là giá trị phổ biến vào năm 2026: nó chỉ loại trừ ~15% thiết bị theo Distribution Dashboard của Android Studio. compileSdk = 36 cung cấp quyền truy cập vào tất cả các API Android 16, và targetSdk = 36 bao gồm các thay đổi hành vi của phiên bản mới nhất. Đối với bản dựng gỡ lỗi, minSdk có thể được hạ xuống để kiểm thử trên các trình giả lập cũ.

Cách chọn minSdkVersion: yếu tố và chiến lược

Chọn minSdkVersion là một quyết định chiến lược dựa trên phân tích khán giả mục tiêu, yêu cầu API và hệ sinh thái thư viện. Không có giá trị đúng duy nhất cho tất cả các dự án. Vào năm 2026, Android Studio khuyến nghị minSdk = 26 (Android 8.0) làm mức cơ sở cho các dự án mới, nhưng đối với ứng dụng B2B hoặc giải pháp doanh nghiệp, giá trị thấp hơn hoặc cao hơn có thể chấp nhận được.

Các yếu tố chọn minSdkVersion

Yếu tố đầu tiên là Distribution Dashboard. Android Studio cung cấp thống kê thiết bị hoạt động theo cấp API dựa trên dữ liệu Google Play, được cập nhật hàng tháng. minSdkVersion phải bao phủ ít nhất 90-95% thiết bị hoạt động của thị trường mục tiêu. Đối với ứng dụng quốc tế có khán giả ở Châu Phi và Đông Nam Á, minSdk nên hạ xuống 21 (Android 5.0) do tỷ lệ thiết bị cũ cao.

Yếu tố thứ hai là yêu cầu phụ thuộc. Mỗi thư viện có minSdkVersion riêng được chỉ định trong tệp kê khai. Nếu thư viện yêu cầu minSdk 29 và ứng dụng yêu cầu minSdk 26, bản dựng sẽ thất bại với lỗi hợp nhất tệp kê khai. Các thư viện Google Play Services hiện đại có minSdk 21, Firebase có minSdk 21, hầu hết thư viện Jetpack có minSdk 21 hoặc 26, và Compose BOM có minSdk 21. Đối với Compose, ngưỡng tối thiểu là API 21.

Yếu tố thứ ba là API cần thiết. Nếu chức năng chính của ứng dụng yêu cầu một API chỉ khả dụng từ một cấp nhất định (ví dụ: PhotoPicker — API 34, Predicted Navigation — API 35), điều này có thể biện minh cho việc tăng minSdk. Tuy nhiên, sự kết hợp giữa backport AndroidX (Activity Result API, NotificationCompat) và kiểm tra thời gian chạy thường được sử dụng để duy trì minSdk thấp.

Chiến lược chọn từng bước

Bước 1: mở Android Studio, File → New Project, và xem minSdk được khuyến nghị trong trình hướng dẫn. Bước 2: kiểm tra Distribution Dashboard trong Android Studio (View → Tool Windows → App Inspection → Distribution Dashboard). Bước 3: phân tích các phụ thuộc của dự án — chạy bản dựng và sửa xung đột hợp nhất tệp kê khai. Bước 4: đánh giá API cấp X nào thực sự được sử dụng mà không có backport. Bước 5: đặt minSdk là giá trị tối thiểu bao phủ 90%+ khán giả mục tiêu và tương thích với tất cả các phụ thuộc.

Phạm vi thiết bị: phân phối cấp API (2026)

Phân phối thiết bị theo cấp API là một chỉ số động thay đổi mỗi quý. Theo Distribution Dashboard của Android Studio tính đến tháng 6 năm 2026, khoảng 85% thiết bị Android hoạt động chạy trên API 26 (Android 8.0) trở lên, 72% trên API 29 (Android 10) trở lên và 55% trên API 31 (Android 12) trở lên. Thị trường Trung Quốc có thống kê riêng do thiếu Google Play Services trên nhiều thiết bị Huawei.

Thiết bị GMS (Google Mobile Services) cập nhật nhanh hơn: tỷ lệ API 31+ trên chúng đạt 68% nhờ các yêu cầu bắt buộc của Google Play đối với nhà sản xuất. Thiết bị không GMS (Huawei, Honor, một số thương hiệu Trung Quốc) có phân phối cũ hơn: tỷ lệ API 31+ trên chúng khoảng 35%. Nếu ứng dụng của bạn nhắm đến thị trường quốc tế, hãy dựa vào thống kê toàn cầu. Nếu nhắm đến Trung Quốc, hãy xem xét phân khúc không GMS.

Kết luận: đối với ứng dụng quốc tế, minSdk 26 bao phủ 85% thiết bị với chi phí tương thích ngược tối thiểu. Đối với ứng dụng có khán giả ở các khu vực đang phát triển, minSdk 21 (97% phạm vi) là hợp lý nhưng sẽ yêu cầu nhiều mã hơn để làm việc với các API cũ. Đối với ứng dụng doanh nghiệp với đội thiết bị được kiểm soát, bạn có thể đặt minSdk 31 và loại bỏ hoàn toàn mã dự phòng.

Tương thích ngược: AndroidX, lint và @RequiresApi

Tương thích ngược là thách thức chính với minSdkVersion thấp. AndroidX (trước đây là Support Library) cung cấp backport của các API hiện đại cho các phiên bản Android cũ: AppCompatActivity cho Material Design, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat và hàng chục thành phần khác. Sử dụng các phiên bản tương đương AndroidX thay vì API gốc là bước đầu tiên hướng tới tương thích.

lint (trình phân tích tĩnh của Android Studio) quét mã để tìm các lệnh gọi API trên minSdkVersion. Nếu một phương thức được chú thích với @RequiresApi ở cấp API cao hơn minSdk và được gọi mà không có kiểm tra, lint sẽ đánh dấu lỗi. Để triệt tiêu cảnh báo, hãy sử dụng chú thích @SuppressLint("NewApi") trên phương thức hoặc @RequiresApi(Build.VERSION_CODES.TIRAMISU) trên toàn bộ hàm. Kiểm tra thời gian chạy qua Build.VERSION.SDK_INT là cơ chế chính để gọi API mới một cách an toàn trên các thiết bị cũ.

// Ví dụ tương thích ngược: PhotoPicker (API 34+) và dự phòng
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity

class ImagePickerActivity : AppCompatActivity() {

    // Activity Result API (AndroidX) — hoạt động trên mọi cấp API
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker chỉ khả dụng từ API 34
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // Sử dụng PhotoPicker (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Dự phòng: GetContent (hoạt động trên tất cả phiên bản)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // Phương thức này không thể được gọi trên API < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

Lớp ImagePickerActivity minh họa ba cấp độ tương thích ngược. Activity Result API từ AndroidX hoạt động trên tất cả các cấp API, do đó việc chọn ảnh cơ bản không phụ thuộc vào minSdk. PhotoPicker (ACTION_PICK_IMAGES) chỉ khả dụng từ API 34 và được gọi dưới kiểm tra SDK_INT với dự phòng sang GetContent. Phương thức usePhotoPickerOnly được đánh dấu bằng @RequiresApi — lint sẽ không cho phép gọi nó mà không có kiểm tra. AppCompat từ AndroidX tự động điều chỉnh chủ đề, fragment và hoạt ảnh theo phiên bản hệ điều hành.

minSdkVersion trong thư viện và mô-đun

Thư viện (AAR, JAR) cũng có minSdkVersion được chỉ định trong tệp kê khai của chúng. Khi kết nối thư viện, Gradle kiểm tra tương thích: nếu minSdk của thư viện cao hơn minSdk của ứng dụng, bản dựng thất bại với lỗi. Đối với thư viện công khai, nên chỉ định minSdk thấp nhất có thể (21 trong hầu hết trường hợp) để không giới hạn người tiêu dùng. Nếu thư viện yêu cầu API 29+, nó mất ~28% người dùng tiềm năng.

Dự án đa mô-đun có thể có các giá trị minSdkVersion khác nhau cho các mô-đun khác nhau. Ví dụ: mô-đun :core:network có thể có minSdk 26, trong khi mô-đun :feature:camera có thể có minSdk 29 (do CameraX với các yêu cầu cụ thể). Google Play yêu cầu minSdk của mô-đun chính :app phải thấp hơn hoặc bằng minSdk của tất cả các mô-đun phụ thuộc. Trong thực tế, tất cả các mô-đun của cùng một ứng dụng thường có cùng minSdk để dễ bảo trì.

// build.gradle.kts — mô-đun thư viện với minSdk thấp
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.mylibrary"
    compileSdk = 36

    defaultConfig {
        minSdk = 21  // Tối thiểu để có phạm vi tối đa
        targetSdk = 36
    }
}

dependencies {
    // AndroidX Core — minSdk 21, thêm backport
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

Mô-đun thư viện với minSdk = 21 tương thích với 97% thiết bị và không giới hạn người tiêu dùng. Nếu thư viện sử dụng API trên 21, nhà phát triển phải thêm kiểm tra thời gian chạy hoặc chỉ định @RequiresApi trên các phương thức liên quan. AndroidX Core KTX (minSdk 21) cung cấp backport cho Context, Bundle, Locale và các lớp hệ thống khác, cho phép thư viện duy trì minSdk thấp.

Lỗi thường gặp khi chọn minSdkVersion

Lỗi khi chọn minSdk có thể tốn kém hàng nghìn lượt cài đặt hoặc nhiều tuần phát triển thêm. Lỗi phổ biến đầu tiên là sao chép minSdk từ mẫu dự án mà không phân tích Distribution Dashboard. Nhiều nhà phát triển giữ nguyên minSdk = 21 từ Mẫu Android Studio, mặc dù minSdk 26 sẽ đủ cho khán giả của họ và giảm số lượng kiểm tra SDK_INT trong mã.

Lỗi thứ hai là minSdk quá cao mà không xem xét thị trường. Nếu bạn đặt minSdk = 31 (Android 12) cho một ứng dụng quốc tế, bạn mất ~45% thiết bị. Đối với một công ty khởi nghiệp hoặc ứng dụng đại chúng, đây là một thảm họa. Luôn kiểm tra Distribution Dashboard trước khi tăng minSdk và sử dụng kiểm thử A/B trong Google Play Console nếu bạn không chắc chắn.

Lỗi thứ ba là bỏ qua minSdk của phụ thuộc. Khi thêm thư viện mới, hãy kiểm tra minSdk của nó trong tài liệu hoặc tệp POM. Firebase ML Kit yêu cầu minSdk 21, một số thư viện máy ảnh tùy chỉnh yêu cầu minSdk 29. Nếu hợp nhất tệp kê khai thất bại trong sản xuất do thư viện mới, việc sửa chữa có thể mất nhiều ngày.

// Ví dụ: kiểm tra tương thích API trong thời gian chạy
fun checkFeatureAvailability(): Boolean {
    // Lỗi điển hình — gọi API mà không kiểm tra SDK_INT
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — sử dụng PhotoPicker
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — sử dụng MediaStore
            true
        }
        else -> {
            // API < 29 — sử dụng ACTION_GET_CONTENT
            true
        }
    }
}

Kiến trúc chính xác cho kiểm tra cấp API là biểu thức when với các phạm vi bao phủ tất cả các giá trị có thể từ minSdk đến compileSdk. Quy tắc chính: bất kỳ lệnh gọi API cấp X nào phải được bảo vệ bằng kiểm tra VERSION.SDK_INT cho tất cả các thiết bị có cấp API từ minSdk đến X. lint giúp phát hiện các lệnh gọi không được kiểm tra, nhưng không thể đảm bảo phạm vi bao phủ đầy đủ cho mã động.