iOS Deployment Target: nó là gì, phiên bản iOS tối thiểu và cấu hình

iOS Deployment Target là gì?

iOS Deployment Target là một tham số cấu hình Xcode chỉ định phiên bản sớm nhất của iOS, iPadOS, tvOS, watchOS hoặc visionOS mà trên đó ứng dụng có thể chạy. Mỗi dự án Xcode chứa cài đặt này riêng cho từng nền tảng. Ví dụ, một ứng dụng iOS có thể có Deployment Target 16.0, trong khi tiện ích mở rộng watchOS có thể là 9.0. Nếu thiết bị của người dùng chạy iOS 15.0, ứng dụng có Target 16.0 sẽ không xuất hiện trên App Store và không thể cài đặt qua phân phối trực tiếp.

Cơ chế Deployment Target dựa trên việc kiểm tra phiên bản hệ điều hành trong quá trình cài đặt. App Store iOS so sánh giá trị Deployment Target từ Info.plist (khóa MinimumOSVersion) với phiên bản hệ điều hành trên thiết bị của người dùng. Nếu phiên bản thiết bị thấp hơn — nút "Tải xuống" bị chặn và API App Store không trả về ứng dụng trong kết quả tìm kiếm cho thiết bị đó. Hành vi tương tự áp dụng cho TestFlight, phân phối ad-hoc và doanh nghiệp.

Theo dữ liệu StatCounter vào tháng 6 năm 2025, iOS 16 chiếm khoảng 48% thiết bị iPhone đang hoạt động, iOS 17 — 35%, iOS 18 — 12%, các phiên bản cũ hơn — khoảng 5%. Chọn Deployment Target 16.0 bao phủ 83% thiết bị, Target 17.0 — 35% (chỉ iOS 17+). Những con số này rất quan trọng cho việc ra quyết định: Target càng cao, đối tượng càng nhỏ, nhưng càng dễ tiếp cận các API SwiftUI và UIKit mới nhất.

Mỗi bản phát hành iOS mới không chỉ thêm tính năng người dùng mà còn thêm API cho nhà phát triển. Các bổ ngữ SwiftUI mới, phương thức UIKit, framework như SwiftData và Observation chỉ khả dụng ở Deployment Target cụ thể. Nhà phát triển phải cân bằng giữa phạm vi tiếp cận đối tượng và khả năng sử dụng công cụ hiện đại.

iOS Deployment Target so với minSdkVersion: so sánh với Android

iOS Deployment Target và minSdkVersion của Android thực hiện cùng một chức năng — đặt phiên bản hệ điều hành tối thiểu cho ứng dụng. Tuy nhiên, cơ chế triển khai và các công cụ liên quan khác nhau. Hiểu những khác biệt này rất hữu ích cho các nhà phát triển làm việc trên cả hai nền tảng và giúp tránh nhầm lẫn khi chuyển đổi giữa các hệ sinh thái.

Trên iOS, phiên bản tối thiểu được đặt qua cài đặt build Xcode (IPHONEOS_DEPLOYMENT_TARGET) và được lưu trong Info.plist (MinimumOSVersion). Trên Android — qua build.gradle (minSdkVersion) và AndroidManifest.xml (<uses-sdk android:minSdkVersion>). iOS không có tương đương cho targetSdkVersion và compileSdkVersion — các thay đổi hành vi trên iOS được quản lý bởi SDK mà ứng dụng được biên dịch (Base SDK) và phiên bản hệ điều hành trên thiết bị.

Sự khác biệt chính là Base SDK trên iOS luôn là phiên bản mới nhất được cài đặt trong Xcode. Nhà phát triển không thể chọn compileSdkVersion như trên Android — ứng dụng luôn biên dịch với SDK mới nhất có sẵn. Các thay đổi hành vi mới trên iOS áp dụng cho tất cả ứng dụng được biên dịch với Base SDK mới, bất kể Deployment Target. Trên Android, targetSdkVersion cung cấp khả năng kiểm soát các thay đổi hành vi; iOS không có sự phân tách này.

Thay đổi hành vi trên iOS so với Android

Không giống như Android, nơi các thay đổi hành vi gắn với targetSdkVersion, iOS áp dụng các thay đổi hành vi cho tất cả ứng dụng được biên dịch với phiên bản Xcode và Base SDK mới. Ví dụ, iOS 13 đã giới thiệu Chế độ tối — tất cả ứng dụng được xây dựng với Xcode 11 và iOS 13 SDK tự động nhận được hỗ trợ giao diện tối, bất kể Deployment Target. Trên Android, một thay đổi tương tự (Scoped Storage) chỉ áp dụng khi targetSdk >= 29. Các nhà phát triển iOS cần chuẩn bị cho các thay đổi hành vi với mỗi Xcode mới, mà không có khả năng trì hoãn.

Kiến thức về cả hai nền tảng cho phép dự đoán hậu quả của việc chọn phiên bản tối thiểu và lập kế hoạch cập nhật mã cho các API mới. Tại IT Sectr, chúng tôi đã sử dụng cả hai hệ sinh thái từ năm 2017 — thực tế cho thấy nên chọn iOS Deployment Target thấp hơn 2–3 phiên bản so với hiện tại để cân bằng giữa phạm vi bao phủ và chức năng.

Cách cấu hình Deployment Target trong Xcode

Cấu hình iOS Deployment Target được thực hiện ở nhiều nơi trong dự án: Target chính, dự án Pods (nếu sử dụng CocoaPods), phụ thuộc Swift Package Manager và target Widget/Extension. Nếu giá trị khác nhau giữa ứng dụng chính và tiện ích mở rộng, App Store sử dụng giá trị lớn nhất — nghĩa là tiện ích mở rộng không thể có Target thấp hơn ứng dụng chính.

Cấu hình trong trình chỉnh sửa dự án Xcode

Mở dự án Xcode → chọn Target → tab General → phần Minimum iOS Deployment. Danh sách thả xuống hiển thị tất cả phiên bản iOS SDK khả dụng được cài đặt trong Xcode. Thay đổi áp dụng cho tất cả lược đồ build. Thay thế — tab Build Settings → iOS Deployment Target (IPHONEOS_DEPLOYMENT_TARGET). Nếu dự án có nhiều target mở rộng (Widget, Watch), mỗi target có Deployment Target riêng.

Cấu hình qua Swift Package Manager

Đối với thư viện phân phối qua SPM, Deployment Target được chỉ định trong Package.swift ở tham số platforms. Thư viện với platforms: [.iOS(.v16)] sẽ chỉ khả dụng cho ứng dụng có Deployment Target iOS 16.0+. Khi thêm thư viện như vậy vào dự án có Target 15.0, Xcode sẽ hiển thị lỗi không tương thích. Trong CocoaPods, Deployment Target được đặt trong Podfile: platform :ios, '16.0'.

// Package.swift — Deployment Target cho thư viện SPM
import PackageDescription

let package = Package(
    name: "MyLibrary",
    platforms: [
        .iOS(.v16),
        .macOS(.v13),
        .watchOS(.v9),
        .tvOS(.v16)
    ],
    products: [
        .library(
            name: "MyLibrary",
            targets: ["MyLibrary"]
        )
    ],
    dependencies: [],
    targets: [
        .target(
            name: "MyLibrary",
            swiftSettings: [
                .enableUpcomingFeature("ConciseMagicFile")
            ]
        )
    ]
)

// Kiểm tra tương thích trong mã
#if swift(>=5.9)
// Tính năng Swift 5.9+ (Xcode 15+)
#endif

Trong ví dụ, Package.swift đặt nền tảng iOS 16+, macOS 13+, watchOS 9+, tvOS 16+. Bất kỳ dự án nào có Deployment Target dưới iOS 16.0 sẽ không thể thêm thư viện này. Tham số swiftSettings bao gồm các tính năng sắp tới cho phiên bản Swift cụ thể. SPM tự động kiểm tra tương thích platforms khi thêm phụ thuộc.

CocoaPods và Podfile

Podfile sử dụng chỉ thị platform :ios, '16.0'. Sau pod install, CocoaPods kiểm tra Deployment Target của từng thư viện pod: nếu ít nhất một có Target cao hơn dự án, quá trình cài đặt sẽ thất bại với lỗi "The iOS deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 17.0, but the range of supported deployment target versions is 16.0 to 17.0". Giải pháp là giảm Target của pod có vấn đề hoặc tăng Target của dự án.

# Podfile — ví dụ với Deployment Target
platform :ios, '16.0'

# Bỏ qua cảnh báo Deployment Target
post_install do |installer|
    installer.pods_project.targets.each do |target|
        target.build_configurations.each do |config|
            config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '16.0'
        end
    end
end

Hook post_install trong Podfile buộc đặt Deployment Target 16.0 cho tất cả thư viện pod. Điều này hữu ích khi một trong các pod chỉ định Target cao hơn mức cần thiết cho chức năng của nó. Chỉ sử dụng điều này nếu bạn chắc chắn rằng pod không sử dụng API từ phiên bản iOS cao hơn.

Kiểm tra @available và #available trong mã Swift và Objective-C

@available và #available là các chỉ thị Swift và Objective-C để gọi an toàn các API chỉ khả dụng trên các phiên bản hệ điều hành nhất định. Nếu Deployment Target của dự án là iOS 16.0 và một phương thức yêu cầu iOS 17.0, gọi trực tiếp sẽ gây ra lỗi runtime trên thiết bị chạy iOS 16.0–16.x. Kiểm tra khả dụng là công cụ bắt buộc để hỗ trợ nhiều phiên bản iOS.

@available — Kiểm tra khai báo

Chỉ thị @available áp dụng cho lớp, phương thức hoặc toàn bộ tệp. Nếu @available(iOS 17.0, *) được chỉ định trước một lớp, toàn bộ lớp chỉ khả dụng trên iOS 17.0+. Cố gắng gọi lớp trên iOS 16.0 sẽ gây ra lỗi runtime. Sử dụng @available để cô lập toàn bộ mô-đun chức năng cụ thể cho một phiên bản hệ điều hành nhất định. Đối với phương thức bên trong lớp, @available cho phép ẩn các hàm riêng lẻ.

#available — Thực thi có điều kiện

Chỉ thị #available (if #available) kiểm tra phiên bản hệ điều hành tại runtime và chỉ thực thi mã khi khớp. Được sử dụng bên trong hàm để chọn giữa triển khai mới và cũ. Trong Objective-C, tương đương là @available(iOS 17.0, *) bên trong if. Để kiểm tra phức tạp hơn, sử dụng ProcessInfo.processInfo.isOperatingSystemAtLeast để so sánh các thành phần phiên bản (major, minor, patch).

import UIKit
import SwiftUI

// 1. @available — toàn bộ lớp chỉ dành cho iOS 17+
@available(iOS 17.0, *)
class ObservationViewModel: ObservableObject {
    @Published var name: String = "User"

    // Sử dụng Observation framework — chỉ khả dụng iOS 17+
    func updateWithObservation() {
        let newName = "Updated via Observation"
        name = newName
    }
}

// 2. #available — gọi có điều kiện bên trong hàm
func configureLiveActivity() {
    if #available(iOS 16.1, *) {
        // API Live Activities — khả dụng từ iOS 16.1
        let activity = Activity<MyAttributes>(
            attributes: MyAttributes(name: "Live"),
            contentState: MyContentState(value: 42)
        )
        Task {
            await activity.activate()
        }
    } else {
        // Dự phòng: thông báo push hoặc không
        print("Live Activities không khả dụng")
    }
}

// 3. ProcessInfo — kiểm tra phiên bản chính xác
func checkOSVersion() {
    let osVersion = ProcessInfo.processInfo.operatingSystemVersion
    print("iOS \(osVersion.majorVersion).\(osVersion.minorVersion).\(osVersion.patchVersion)")

    // So sánh thành phần
    if osVersion.majorVersion >= 17 {
        print("Đã phát hiện iOS 17+")
    }
}

// 4. Objective-C @available
// Objective-C sử dụng @available:
// if (@available(iOS 17.0, *)) { }

// 5. @available với đối số unavailable
@available(*, unavailable, message: "Use configureWithSwiftUI instead")
func legacyConfigureMethod() { }

Lớp ObservationViewModel sử dụng @available để cô lập chức năng iOS 17. Hàm configureLiveActivity sử dụng #available để kiểm tra Live Activities (iOS 16.1+) với triển khai dự phòng. ProcessInfo kiểm tra phiên bản hệ điều hành chính xác. @available(*, unavailable) đánh dấu phương thức không khả dụng trên tất cả phiên bản — để di chuyển sang API mới. Nếu không có các kiểm tra này, ứng dụng có Deployment Target 16.0 sẽ gặp sự cố trên thiết bị iOS 16.0 khi gọi API iOS 17.

Objective-C và @available

Objective-C sử dụng @available(iOS 17.0, *) với cùng ngữ nghĩa như Swift #available. Sự khác biệt: Objective-C kiểm tra tại runtime, Swift #available cũng tại runtime nhưng có gợi ý trình biên dịch để tối ưu hóa nhánh. Đối với mã Objective-C tương tác với Swift, cần kiểm tra khả dụng ở phía Objective-C — cầu nối Swift không thêm kiểm tra tự động.

Cách chọn Deployment Target phù hợp cho dự án của bạn

Chọn iOS Deployment Target là một quyết định chiến lược ảnh hưởng đến ba khía cạnh: phạm vi tiếp cận đối tượng, API khả dụng và độ phức tạp bảo trì mã. Không có giá trị đúng duy nhất — lựa chọn phụ thuộc vào đối tượng mục tiêu của ứng dụng, các tính năng tối thiểu cần thiết và nguồn lực nhóm để hỗ trợ tương thích ngược.

Yếu tố đầu tiên — thống kê sử dụng phiên bản iOS Apple công bố dữ liệu cài đặt iOS tại WWDC và trong Apple Developer Dashboard. Tính đến tháng 6 năm 2025, phân bố là: iOS 15 — ~7%, iOS 16 — ~48%, iOS 17 — ~35%, iOS 18 — ~10%. Chọn Target 16.0 cung cấp 83% phạm vi bao phủ, Target 17.0 — 35%. Đối với ứng dụng đại chúng (mạng xã hội, nhắn tin, thương mại điện tử), Target 16.0 được khuyến nghị. Đối với ứng dụng B2B chuyên biệt có yêu cầu API cụ thể — Target 17.0.

Yếu tố thứ hai — API cần thiết Nếu tính năng chính của ứng dụng yêu cầu SwiftData (iOS 17+), Observation (iOS 17+) hoặc Live Activities (iOS 16.1+), Target không thể thấp hơn phiên bản yêu cầu. Phân tích API cần thiết ở giai đoạn thiết kế ngăn chặn tình huống phát hiện ra cần Target cao hơn giữa quá trình phát triển. Sử dụng kiểm tra khả dụng làm kế hoạch dự phòng, không phải chiến lược chính.

Yếu tố thứ ba — nguồn lực kiểm thử Hỗ trợ các phiên bản iOS cũ yêu cầu kiểm thử trên trình mô phỏng và thiết bị thực với các phiên bản đó. iOS 15 được kiểm thử trên iPhone 6s/7, iOS 16 — trên iPhone 8/X, iOS 17 — trên iPhone XS/XR. Mỗi phiên bản tương thích ngược bổ sung làm tăng thời gian QA. Nếu nhóm nhỏ, việc chọn Target thấp hơn 2–3 phiên bản so với hiện tại (16.0) là hợp lý — cân bằng giữa phạm vi bao phủ và công sức.

Thư viện và SDK nên có Deployment Target thấp nhất có thể (15.0 hoặc thậm chí 14.0) — người dùng thư viện có thể có Target cao hơn bạn. Nếu thư viện yêu cầu iOS 17.0, một nửa dự án sẽ không thể sử dụng nó. Đối với ứng dụng, mặt khác, bạn có thể cho phép Target cao hơn để truy cập API mới.

Cách giảm Deployment Target sau khi đã tăng

Giảm iOS Deployment Target là một nhiệm vụ phát sinh khi cần mở rộng đối tượng hoặc khi xuất bản thư viện tương thích với các dự án cũ. Không giống như tăng, giảm yêu cầu làm việc tích cực với mã: bạn cần thay thế tất cả các lệnh gọi trực tiếp đến API không khả dụng trong Target mới (thấp hơn) bằng kiểm tra #available với triển khai dự phòng.

Bước đầu tiên — kiểm kê API Xcode không hiển thị lỗi biên dịch khi giảm Target — nó chỉ cảnh báo bằng cảnh báo màu vàng. Bạn cần tìm tất cả phương thức và lớp được đánh dấu @available(iOS N+, *) với N cao hơn Target mới. Sử dụng tìm kiếm dự án (Cmd+Shift+F) với mẫu "available(iOS". Mỗi lệnh gọi như vậy là ứng viên để tái cấu trúc.

Bước thứ hai — thay thế bằng kiểm tra #available Mỗi lệnh gọi API từ phiên bản cao hơn được bọc trong if #available(iOS N+, *) { } else { }. Đối với toàn bộ lớp, sử dụng #if os(iOS) với @available ở cấp độ kiểu. Nếu API không có dự phòng hợp lý (ví dụ: Live Activities), chức năng sẽ bị vô hiệu hóa cho các phiên bản cũ với thông báo cho người dùng.

import UIKit
import SwiftUI

// Giảm Deployment Target từ 17.0 xuống 16.0

// TRƯỚC (@available iOS 17.0):
@available(iOS 17.0, *)
func setupObservation() {
    // Observation framework — chỉ iOS 17+
    let model = ObservationViewModel()
    // ...
}

// SAU (kiểm tra #available):
func setupObservationCompatible() {
    if #available(iOS 17.0, *) {
        // iOS 17+: Observation framework
        let model = ObservationViewModel()
        // ...
    } else {
        // iOS 16.x: ObservableObject với @Published
        let model = LegacyObservableViewModel()
        // ...
    }
}

// Cho API UIKit iOS 17+:
@available(iOS 17.0, *)
class ModernViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        // Sử dụng UIKit TraitChanges (iOS 17+)
        registerForTraitChanges([UITraitVerticalSizeClass.self]) { _, _ in }
    }
}

// Dự phòng cho iOS 16:
class LegacyViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        // Không có registerForTraitChanges — sử dụng traitCollectionDidChange
    }

    override func traitCollectionDidChange(_: UITraitCollection?) {
        super.traitCollectionDidChange(nil)
        // Xử lý thay đổi traits cho iOS 16
    }
}

// Factory để chọn triển khai theo phiên bản iOS
func makeViewController() -> UIViewController {
    if #available(iOS 17.0, *) {
        return ModernViewController()
    } else {
        return LegacyViewController()
    }
}

Mã minh họa việc giảm Target từ iOS 17.0 xuống 16.0. Hàm setupObservation được thay thế bằng setupObservationCompatible với kiểm tra #available. ViewController được chia thành Modern (iOS 17+) và Legacy (iOS 16) với factory makeViewController chọn triển khai theo phiên bản hệ điều hành. Kiến trúc này cho phép hỗ trợ hai Deployment Target mà không nhân đôi toàn bộ mã nguồn — chỉ các mô-đun được quản lý phiên bản.

Cảnh báo Xcode và cách khắc phục

Sau khi giảm Deployment Target, Xcode sẽ đánh dấu màu vàng tất cả lệnh gọi API không khả dụng trong Target mới. Cảnh báo "In iOS 16.0 and later" có nghĩa là phương thức yêu cầu phiên bản cao hơn. Giải pháp: thêm @available hoặc if #available (khuyến nghị), triệt tiêu qua @available(*, deprecated) để di chuyển dần dần, hoặc xóa lệnh gọi. Bật "Treat Warnings as Errors" trong dự án sẽ biến các cảnh báo này thành lỗi biên dịch — hãy bật tùy chọn này để kiểm soát.