iOS Deployment Target: چیست، حداقل نسخه iOS و پیکربندی

iOS Deployment Target چیست؟

iOS Deployment Target — پارامتر پیکربندی Xcode که قدیمی‌ترین نسخه iOS، iPadOS، tvOS، watchOS یا visionOS را مشخص می‌کند که برنامه می‌تواند روی آن اجرا شود. هر پروژه Xcode این تنظیمات را برای هر پلتفرم جداگانه دارد. برای مثال، برنامه iOS می‌تواند Deployment Target 16.0 داشته باشد و افزونه watchOS — 9.0. اگر دستگاه کاربر روی iOS 15.0 کار کند، برنامه با Target 16.0 در App Store نمایش داده نمی‌شود و از طریق توزیع مستقیم نصب نخواهد شد.

مکانیزم عملکرد Deployment Target بر اساس بررسی نسخه OS در هنگام نصب است. iOS App Store مقدار Deployment Target از Info.plist (کلید MinimumOSVersion) را با نسخه OS روی دستگاه کاربر مقایسه می‌کند. اگر نسخه دستگاه پایین‌تر باشد — دکمه "دریافت" مسدود می‌شود و API App Store برنامه را در نتایج جستجو برای این دستگاه برنمی‌گرداند. رفتار مشابهی برای TestFlight، توزیع ad-hoc و enterprise اعمال می‌شود.

طبق داده‌های StatCounter تا ژوئن 2025، iOS 16 حدود 48% از دستگاه‌های فعال iPhone را تشکیل می‌دهد، iOS 17 — 35%، iOS 18 — 12%، نسخه‌های قدیمی‌تر — حدود 5%. انتخاب Deployment Target 16.0، 83% دستگاه‌ها را پوشش می‌دهد، Target 17.0 — 35% (فقط iOS 17+). این اعداد برای تصمیم‌گیری حیاتی هستند: هرچه Target بالاتر باشد، مخاطب کمتر است، اما جدیدترین APIهای SwiftUI و UIKit در دسترس‌تر هستند.

هر نسخه جدید iOS نه تنها قابلیت‌های کاربری، بلکه APIهایی برای توسعه‌دهندگان اضافه می‌کند. modifierهای جدید SwiftUI، متدهای UIKit، فریمورک‌هایی مانند SwiftData و Observation فقط با Deployment Target خاصی در دسترس هستند. توسعه‌دهنده باید بین پوشش مخاطب و در دسترس بودن ابزارهای مدرن تعادل برقرار کند.

iOS Deployment Target در مقابل minSdkVersion: مقایسه با Android

iOS Deployment Target و minSdkVersion Android عملکرد یکسانی دارند — حداقل نسخه OS را برای برنامه تعیین می‌کنند. با این حال، مکانیزم‌های پیاده‌سازی و ابزارهای همراه متفاوت هستند. درک این تفاوت‌ها برای توسعه‌دهندگانی که روی هر دو پلتفرم کار می‌کنند مفید است و به جلوگیری از سردرگمی هنگام جابجایی بین اکوسیستم‌ها کمک می‌کند.

در iOS، حداقل نسخه از طریق تنظیمات ساخت Xcode (IPHONEOS_DEPLOYMENT_TARGET) تنظیم و در Info.plist (MinimumOSVersion) ذخیره می‌شود. در Android — از طریق build.gradle (minSdkVersion) و AndroidManifest.xml (<uses-sdk android:minSdkVersion>). iOS معادلی برای targetSdkVersion و compileSdkVersion ندارد — تغییرات رفتاری در iOS توسط SDK که برنامه با آن کامپایل شده (Base SDK) و نسخه OS روی دستگاه مدیریت می‌شود.

تفاوت کلیدی — Base SDK در iOS همیشه آخرین نسخه نصب‌شده در Xcode است. توسعه‌دهنده نمی‌تواند compileSdkVersion را مانند Android انتخاب کند — برنامه همیشه علیه آخرین SDK موجود کامپایل می‌شود. تغییرات رفتاری جدید در iOS بدون توجه به Deployment Target به همه برنامه‌های کامپایل‌شده با Base SDK جدید اعمال می‌شود. در Android، targetSdkVersion کنترل تغییرات رفتاری را می‌دهد، در iOS چنین تقسیم‌بندی وجود ندارد.

تغییرات رفتاری در iOS در مقابل Android

برخلاف Android که تغییرات رفتاری به targetSdkVersion وابسته هستند، iOS تغییرات رفتار را به همه برنامه‌های کامپایل‌شده با نسخه جدید Xcode و Base SDK اعمال می‌کند. برای مثال، iOS 13 حالت تاریک (Dark Mode) را معرفی کرد — همه برنامه‌های ساخته‌شده با Xcode 11 و iOS 13 SDK، بدون توجه به Deployment Target، به طور خودکار پشتیبانی از تم تاریک را دریافت می‌کردند. در Android، تغییر مشابه (Scoped Storage) فقط با targetSdk >= 29 اعمال می‌شود. توسعه‌دهنده iOS باید با هر Xcode جدید برای تغییرات رفتاری آماده باشد، بدون امکان تأخیر.

آشنایی با هر دو پلتفرم امکان پیش‌بینی پیامدهای انتخاب حداقل نسخه و برنامه‌ریزی به‌روزرسانی‌های کد برای APIهای جدید را فراهم می‌کند. در IT Sectr از سال 2017 از هر دو اکوسیستم استفاده می‌کنیم — تجربه نشان می‌دهد که iOS Deployment Target باید 2–3 نسخه پایین‌تر از نسخه فعلی برای تعادل پوشش و عملکرد انتخاب شود.

چگونه Deployment Target را در Xcode پیکربندی کنیم

پیکربندی iOS Deployment Target در چند مکان پروژه انجام می‌شود: Target اصلی، پروژه Pods (اگر CocoaPods استفاده می‌شود)، وابستگی‌های Swift Package Manager و Targetهای Widget/Extension. اگر مقادیر بین برنامه اصلی و افزونه‌ها متفاوت باشند، App Store از حداکثر همه آنها استفاده می‌کند — یعنی افزونه نمی‌تواند Target پایین‌تری نسبت به برنامه اصلی داشته باشد.

پیکربندی در ویرایشگر پروژه Xcode

پروژه Xcode را باز کنید → Target را انتخاب کنید → برگه General → بخش Minimum iOS Deployment. لیست کشویی تمام نسخه‌های iOS SDK نصب‌شده در Xcode را نشان می‌دهد. تغییر برای همه طرح‌های ساخت اعمال می‌شود. جایگزین — برگه Build Settings → iOS Deployment Target (IPHONEOS_DEPLOYMENT_TARGET). اگر پروژه شامل چند Target-افزونه (Widget, Watch) باشد، هر کدام Deployment Target خود را دارد.

پیکربندی از طریق Swift Package Manager

برای کتابخانه‌های توزیع‌شده از طریق SPM، Deployment Target در Package.swift در پارامتر platforms مشخص می‌شود. کتابخانه با platforms: [.iOS(.v16)] فقط برای برنامه‌های با Deployment Target iOS 16.0+ در دسترس خواهد بود. هنگام اتصال چنین کتابخانه‌ای به پروژه با Target 15.0، Xcode خطای ناسازگاری می‌دهد. در CocoaPods، Deployment Target در Podfile تنظیم می‌شود: platform :ios, '16.0'.

// Package.swift — Deployment Target برای کتابخانه 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")
            ]
        )
    ]
)

// بررسی سازگاری در کد
#if swift(>=5.9)
// قابلیت‌های Swift 5.9+ (Xcode 15+)
#endif

در مثال Package.swift پلتفرم‌های iOS 16+، macOS 13+، watchOS 9+، tvOS 16+ تنظیم شده‌اند. هر پروژه با Deployment Target پایین‌تر از iOS 16.0 نمی‌تواند این کتابخانه را متصل کند. پارامتر swiftSettings شامل upcoming features برای نسخه خاص Swift است. SPM به طور خودکار سازگاری platforms را هنگام افزودن وابستگی بررسی می‌کند.

CocoaPods و Podfile

Podfile از دستور platform :ios, '16.0' استفاده می‌کند. پس از pod install، CocoaPods Deployment Target هر pod-کتابخانه را بررسی می‌کند: اگر حداقل یکی Target بالاتری نسبت به پروژه داشته باشد، نصب با خطا "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" پایان می‌یابد. راه‌حل — کاهش Target pod مشکل‌دار یا افزایش Target پروژه.

# Podfile — مثال با Deployment Target
platform :ios, '16.0'

# نادیده گرفتن هشدارهای 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

هوک post_install در Podfile به اجبار Deployment Target 16.0 را برای همه pod-کتابخانه‌ها تنظیم می‌کند. این زمانی مفید است که یکی از podها Target بالاتری نسبت به نیاز عملکردی خود مشخص می‌کند. فقط در صورتی از این استفاده کنید که مطمئن هستید pod از API نسخه بالاتر iOS استفاده نمی‌کند.

بررسی‌های @available و #available در کد Swift و Objective-C

@available و #available — دستورات Swift و Objective-C برای فراخوانی ایمن APIهایی که فقط در نسخه‌های خاصی از OS در دسترس هستند. اگر Deployment Target پروژه iOS 16.0 باشد و متد به iOS 17.0 نیاز داشته باشد، فراخوانی مستقیم باعث crash در runtime روی دستگاه‌های با iOS 16.0-16.x می‌شود. بررسی‌های در دسترس بودن — ابزار اجباری برای پشتیبانی از چند نسخه iOS.

@available — بررسی اعلامی

دستور @available به کلاس‌ها، متدها یا فایل‌های کامل اعمال می‌شود. اگر @available(iOS 17.0, *) قبل از کلاس مشخص شده باشد، کل کلاس فقط در iOS 17.0+ در دسترس است. تلاش برای فراخوانی کلاس در iOS 16.0 منجر به خطای runtime می‌شود. از @available برای ایزوله کردن ماژول‌های کامل قابلیت‌های خاص نسخه OS استفاده کنید. برای متدهای داخل کلاس، @available امکان پنهان کردن توابع جداگانه را می‌دهد.

#available — اجرای شرطی

دستور #available (if #available) نسخه OS را در runtime بررسی می‌کند و کد را فقط در صورت مطابقت اجرا می‌کند. در داخل توابع برای انتخاب بین پیاده‌سازی جدید و قدیمی استفاده می‌شود. در Objective-C معادل — @available(iOS 17.0, *) داخل if. برای بررسی‌های پیچیده‌تر از ProcessInfo.processInfo.isOperatingSystemAtLeast برای مقایسه اجزای نسخه (major, minor, patch) استفاده کنید.

import UIKit
import SwiftUI

// 1. @available — کل کلاس فقط برای iOS 17+
@available(iOS 17.0, *)
class ObservationViewModel: ObservableObject {
    @Published var name: String = "User"

    // از فریمورک Observation استفاده می‌کند — فقط iOS 17+ در دسترس
    func updateWithObservation() {
        let newName = "Updated via Observation"
        name = newName
    }
}

// 2. #available — فراخوانی شرطی داخل تابع
func configureLiveActivity() {
    if #available(iOS 16.1, *) {
        // Live Activities API — از iOS 16.1 در دسترس
        let activity = Activity<MyAttributes>(
            attributes: MyAttributes(name: "Live"),
            contentState: MyContentState(value: 42)
        )
        Task {
            await activity.activate()
        }
    } else {
        // Fallback: اعلان push یا هیچ
        print("Live Activities در دسترس نیست")
    }
}

// 3. ProcessInfo — بررسی دقیق نسخه
func checkOSVersion() {
    let osVersion = ProcessInfo.processInfo.operatingSystemVersion
    print("iOS \(osVersion.majorVersion).\(osVersion.minorVersion).\(osVersion.patchVersion)")

    // مقایسه اجزا
    if osVersion.majorVersion >= 17 {
        print("iOS 17+ شناسایی شد")
    }
}

// 4. Objective-C @available
// در Objective-C از @available استفاده می‌شود:
// if (@available(iOS 17.0, *)) { }

// 5. @available با آرگومان unavailable
@available(*, unavailable, message: "Use configureWithSwiftUI instead")
func legacyConfigureMethod() { }

کلاس ObservationViewModel از @available برای ایزوله کردن قابلیت iOS 17 استفاده می‌کند. تابع configureLiveActivity از #available برای بررسی Live Activities (iOS 16.1+) با پیاده‌سازی fallback استفاده می‌کند. ProcessInfo نسخه دقیق OS را بررسی می‌کند. @available(*, unavailable) متد را در همه نسخه‌ها غیرقابل دسترس علامت‌گذاری می‌کند — برای مهاجرت به API جدید. بدون این بررسی‌ها، برنامه با Deployment Target 16.0 در دستگاه‌های iOS 16.0 هنگام فراخوانی API iOS 17 crash می‌کند.

Objective-C و @available

Objective-C از @available(iOS 17.0, *) با همان معنای Swift #available استفاده می‌کند. تفاوت: Objective-C در runtime بررسی می‌کند، Swift #available — همچنین runtime، اما با نکاتی برای کامپایلر برای بهینه‌سازی انشعاب. برای کد Objective-C که با Swift تعامل دارد، بررسی‌های در دسترس بودن در سمت Objective-C ضروری است — Swift-bridging بررسی‌های خودکار اضافه نمی‌کند.

چگونه Deployment Target مناسب را برای پروژه انتخاب کنیم

انتخاب iOS Deployment Target — تصمیم استراتژیک مؤثر بر سه جنبه: پوشش مخاطب، APIهای موجود و پیچیدگی نگهداری کد. یک مقدار صحیح واحد وجود ندارد — انتخاب به مخاطب هدف برنامه، حداقل قابلیت‌های مورد نیاز و منابع تیم برای پشتیبانی از سازگاری معکوس بستگی دارد.

عامل اول — آمار استفاده از نسخه‌های iOS. Apple داده‌های نصب iOS را در WWDC و Apple Developer Dashboard منتشر می‌کند. تا ژوئن 2025 توزیع: iOS 15 — ~7%، iOS 16 — ~48%، iOS 17 — ~35%، iOS 18 — ~10%. انتخاب Target 16.0 پوشش 83% را می‌دهد، Target 17.0 — 35%. برای برنامه انبوه (شبکه‌های اجتماعی، پیام‌رسان‌ها، تجارت الکترونیک) Target 16.0 توصیه می‌شود. برای برنامه B2B خاص با APIهای خاص — Target 17.0.

عامل دوم — APIهای مورد نیاز. اگر قابلیت کلیدی برنامه نیاز به SwiftData (iOS 17+)، Observation (iOS 17+) یا Live Activities (iOS 16.1+) دارد، Target نمی‌تواند پایین‌تر از نسخه مورد نیاز باشد. تحلیل APIهای مورد نیاز در مرحله طراحی از وضعیتی جلوگیری می‌کند که در میانه توسعه مشخص شود Target بالاتری نیاز است. از Availability Checks به عنوان گزینه پشتیبان استفاده کنید، نه به عنوان برنامه اصلی.

عامل سوم — منابع تست. پشتیبانی از نسخه‌های قدیمی iOS نیاز به آزمایش روی شبیه‌سازها و دستگاه‌های واقعی با آن نسخه‌ها دارد. iOS 15 روی iPhone 6s/7، iOS 16 — روی iPhone 8/X، iOS 17 — روی iPhone XS/XR تست می‌شود. هر نسخه اضافی backward compatibility زمان QA را افزایش می‌دهد. اگر تیم کوچک است، انتخاب Target 2–3 نسخه پایین‌تر از نسخه فعلی (16.0) منطقی است — تعادل بین پوشش و هزینه کار.

کتابخانه‌ها و SDKها باید کمترین Deployment Target ممکن (15.0 یا حتی 14.0) را داشته باشند — مصرف‌کنندگان کتابخانه می‌توانند هر Target بالاتری از شما داشته باشند. اگر کتابخانه به iOS 17.0 نیاز داشته باشد، نیمی از پروژه‌ها نمی‌توانند آن را متصل کنند. برای برنامه‌ها، برعکس، می‌توانید Target بالاتری برای دسترسی به APIهای جدید بپردازید.

چگونه Deployment Target را پس از افزایش کاهش دهیم

کاهش iOS Deployment Target — وظیفه‌ای که هنگام نیاز به گسترش مخاطب یا انتشار کتابخانه با سازگاری با پروژه‌های قدیمی ایجاد می‌شود. برخلاف افزایش، کاهش نیاز به کار فعال با کد دارد: باید همه فراخوانی‌های مستقیم APIهای غیرقابل دسترس در Target جدید (پایین‌تر) را با بررسی‌های #available با پیاده‌سازی‌های fallback جایگزین کنید.

گام اول — موجودی API. Xcode هنگام کاهش Target خطای کامپایل نمی‌دهد — فقط با هشدارهای زرد هشدار می‌دهد. باید همه متدها و کلاس‌های علامت‌گذاری‌شده با @available(iOS N+, *) که N بالاتر از Target جدید است را پیدا کنید. از جستجوی پروژه (Cmd+Shift+F) با الگوی "available(iOS" استفاده کنید. هر چنین فراخوانی — نامزدی برای بازسازی.

گام دوم — جایگزینی با بررسی‌های #available. هر فراخوانی API از نسخه بالاتر در if #available(iOS N+, *) { } else { } قرار می‌گیرد. برای کلاس‌های کامل از #if os(iOS) با @available در سطح نوع استفاده کنید. اگر API fallback معقولی ندارد (مثلاً Live Activities)، قابلیت برای نسخه‌های قدیمی با اطلاع‌رسانی به کاربر غیرفعال می‌شود.

import UIKit
import SwiftUI

// کاهش Deployment Target از 17.0 به 16.0

// قبلی (@available iOS 17.0):
@available(iOS 17.0, *)
func setupObservation() {
    // Observation framework — فقط iOS 17+
    let model = ObservationViewModel()
    // ...
}

// بعدی (بررسی #available):
func setupObservationCompatible() {
    if #available(iOS 17.0, *) {
        // iOS 17+: Observation framework
        let model = ObservationViewModel()
        // ...
    } else {
        // iOS 16.x: ObservableObject با @Published
        let model = LegacyObservableViewModel()
        // ...
    }
}

// برای UIKit iOS 17+ API:
@available(iOS 17.0, *)
class ModernViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        // از UIKit TraitChanges (iOS 17+) استفاده می‌کند
        registerForTraitChanges([UITraitVerticalSizeClass.self]) { _, _ in }
    }
}

// Fallback برای iOS 16:
class LegacyViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        // registerForTraitChanges وجود ندارد — از traitCollectionDidChange استفاده می‌کنیم
    }

    override func traitCollectionDidChange(_: UITraitCollection?) {
        super.traitCollectionDidChange(nil)
        // پردازش تغییرات traits برای iOS 16
    }
}

// کارخانه برای انتخاب پیاده‌سازی بر اساس نسخه iOS
func makeViewController() -> UIViewController {
    if #available(iOS 17.0, *) {
        return ModernViewController()
    } else {
        return LegacyViewController()
    }
}

کد کاهش Target از iOS 17.0 به 16.0 را نشان می‌دهد. تابع setupObservation با setupObservationCompatible با بررسی #available جایگزین شده است. ViewController به Modern (iOS 17+) و Legacy (iOS 16) با کارخانه makeViewController تقسیم شده است که پیاده‌سازی را بر اساس نسخه OS انتخاب می‌کند. چنین معماری امکان نگهداری دو Deployment Target را بدون تکرار کل پایگاه کد فراهم می‌کند — فقط ماژول‌های نسخه‌بندی‌شده.

هشدارهای Xcode و رفع آنها

پس از کاهش Deployment Target، Xcode همه فراخوانی‌های API غیرقابل دسترس در Target جدید را زرد رنگ می‌کند. هشدار "In iOS 16.0 and later" به معنی نیاز متد به نسخه بالاتر است. راه‌حل‌ها: افزودن @available یا if #available (توصیه می‌شود)، سرکوب با @available(*, deprecated) برای مهاجرت تدریجی، یا حذف فراخوانی. تنظیم "Treat Warnings as Errors" در پروژه این هشدارها را به خطاهای کامپایل تبدیل می‌کند — این گزینه را برای کنترل فعال کنید.