CocoaPods: مفاهیم کلیدی، مدیر وابستگی برای iOS

CocoaPods چیست؟

CocoaPods — مدیر وابستگی برای اکوسیستم Apple، نوشته شده به Ruby و منتشر شده در سال ۲۰۱۱ توسط Eladio Lopez. CocoaPods مشکل یکپارچه‌سازی کتابخانه‌های شخص ثالث در پروژه‌های Xcode را حل می‌کند: به جای کپی دستی فایل‌ها و پیکربندی linker flags، توسعه‌دهنده وابستگی‌ها را در Podfile توصیف کرده و pod install را اجرا می‌کند. CocoaPods به طور خودکار فایل‌های منبع را بارگیری، پرچم‌های کامپایلر را پیکربندی و فضای کاری .xcworkspace را ایجاد می‌کند.

معماری CocoaPods شامل سه مؤلفه است: CocoaPods.app (ابزار CLI)، Specs (رجیستر مرکزی مشخصات در GitHub) و Podfile (پیکربندی پروژه). رجیستر Specs شامل بیش از ۱۰۰٬۰۰۰ کتابخانه با تاریخچه نسخه است. هنگام اجرای pod install، CocoaPods آخرین نسخه رجیستر را بارگیری می‌کند (pod repo update)، وابستگی‌ها را پیدا می‌کند، درخت نسخه را حل کرده و .xcworkspace را با یکپارچه‌سازی تمام podها تولید می‌کند. هر کتابخانه به عنوان یک target جداگانه کامپایل می‌شود که امکان جداسازی وابستگی‌ها و جلوگیری از تداخل نام‌ها را فراهم می‌کند.

CocoaPods با Xcode یکپارچه شده است: فایل‌های Pods.xccconfig را با مسیرهای هدر و پرچم‌های linker تولید می‌کند و همچنین User Script Sandboxing را پیکربندی می‌کند. برای استفاده از CocoaPods در macOS، Ruby ۲.۶+ (از قبل روی تمام Macها نصب شده) و Xcode با Command Line Tools مورد نیاز است. آمار: در سال ۲۰۲۵، CocoaPods بیش از ۱۰ میلیارد بارگیری pod را پردازش کرد و یک پروژه متوسط iOS شامل ۱۵ تا ۴۰ وابستگی از طریق CocoaPods است.

CocoaPods چگونه کار می‌کند

CocoaPods هر کتابخانه را به عنوان یک مخزن Git جداگانه بارگیری می‌کند، مشخصات .podspec آن را بررسی کرده و به یک فریم‌ورک ایستا یا کتابخانه پویا کامپایل می‌کند. Podها می‌توانند به podهای دیگر وابسته باشند — CocoaPods یک گراف وابستگی می‌سازد و تداخل نسخه‌ها را حل می‌کند. اگر دو کتابخانه نسخه‌های متفاوتی از یک وابستگی را نیاز داشته باشند، CocoaPods سعی می‌کند نسخه سازگاری پیدا کند یا خطا گزارش می‌دهد. تمام وابستگی‌ها و نسخه‌های آنها در فایل Podfile.lock ثابت می‌شوند که باید به سیستم کنترل نسخه اضافه شود.

مزایای CocoaPods در مقایسه با یکپارچه‌سازی دستی: مدیریت خودکار وابستگی‌ها، رجیستر متمرکز کتابخانه‌ها، پشتیبانی از زیرمشخصات (subspecs)، امکان ایجاد مخازن خصوصی و نسخه‌گذاری از طریق کنترل معنایی. برای تیم توسعه‌دهندگان، CocoaPods تضمین می‌کند که همه اعضا از نسخه‌های یکسان کتابخانه‌ها استفاده می‌کنند — Podfile.lock تکرارپذیری ساخت را در هر ماشینی تضمین می‌کند.

Podfile: ساختار، نحو و مثال‌ها

Podfile — فایل پیکربندی به زبان Ruby که وابستگی‌های پروژه Xcode را تعریف می‌کند. Podfile در ریشه پروژه در کنار .xcodeproj قرار می‌گیرد. نحو CocoaPods بر اساس Ruby DSL (زبان خاص دامنه) است که امکان استفاده از متغیرها، شرط‌ها و حلقه‌ها را فراهم می‌کند. یک Podfile حداقلی شامل پلتفرم و حداقل یک وابستگی است.

platform :ios, '15.0'

target 'MyApp' do
  pod 'Alamofire', '~> 5.9'
  pod 'SnapKit', '~> 5.7'
  pod 'Kingfisher', '~> 8.0'
end

خط کلیدی platform :ios, '15.0' حداقل نسخه iOS را تعیین می‌کند. دستور target 'MyApp' وابستگی‌ها را برای یک target خاص گروه‌بندی می‌کند. هر خط pod 'Name', '~> version' نام کتابخانه و نسخه را مشخص می‌کند. عملگر '~> 5.9' به معنای «هر نسخه‌ای از ۵٫۹ تا ۶٫۰، به جز ۶٫۰» است — این نسخه‌گذاری معنایی است که از breaking changes محافظت می‌کند.

ثابت‌سازی نسخه‌ها و گزینه‌ها

CocoaPods از عملگرهای نسخه انعطاف‌پذیر پشتیبانی می‌کند: '= 1.0' (نسخه دقیق)، '> = 1.0' (حداقل)، '< 2.0' (حداکثر)، '~ > 1.2.3' (فقط patch). می‌توان کتابخانه را از پوشه محلی از طریق pod 'MyLib', :path => '../MyLib' متصل کرد. برای اتصال از Git: pod 'MyLib', :git => 'https://github.com/user/MyLib.git', :tag => '1.0.0'.

platform :ios, '15.0'
use_frameworks! :linkage => :static
inhibit_all_warnings!

target 'MyApp' do
  pod 'Alamofire', '~> 5.9'
  pod 'Firebase/Crashlytics', '~> 11.0'

  target 'MyAppTests' do
    inherit! :search_paths
    pod 'Nimble', '~> 13.0'
  end
end

target 'MyWatchExtension' do
  platform :watchos, '9.0'
  pod 'Alamofire', '~> 5.9'
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
    end
  end
end

use_frameworks! کامپایل podها را به عنوان فریم‌ورک به جای کتابخانه‌های ایستا فعال می‌کند (رفتار پیش‌فرض از Xcode ۱۵+). ویژگی :linkage => :static فریم‌ورک‌ها را به صورت اجباری ایستا می‌کند و اندازه برنامه را کاهش می‌دهد. inhibit_all_warnings! هشدارهای podها را غیرفعال می‌کند — برای تمیزی لاگ ساخت مفید است. targetهای تودرتو (مثلاً برای تست‌ها) با inherit! :search_paths فقط مسیرهای جستجو را دریافت می‌کنند بدون اینکه همه وابستگی‌ها را دوباره کامپایل کنند. بلوک post_install پیکربندی ساخت را برای همه targetهای pod تنظیم می‌کند — این یک الگوی استاندارد برای تعیین حداقل نسخه iOS واحد است.

Podfile.lock به طور خودکار در pod install تولید می‌شود. این فایل نسخه‌های دقیق همه وابستگی‌های نصب شده را از جمله وابستگی‌های انتقالی ثابت می‌کند. فایل lock باید در مخزن نگهداری شود — بدون آن، pod install در ماشین دیگر ممکن است نسخه‌های متفاوتی نصب کند. دستور pod update PodName یک pod خاص را به‌روزرسانی کرده و Podfile.lock را تغییر می‌دهد. pod outdated لیست podهایی را نشان می‌دهد که نسخه‌های جدیدتر برای آنها در دسترس است.

Podspec: ایجاد و انتشار کتابخانه

Podspec — فایل Ruby با پسوند .podspec که کتابخانه را برای CocoaPods توصیف می‌کند. Podspec شامل فراداده (نام، نسخه، نویسنده)، کد منبع، وابستگی‌ها، فریم‌ورک‌های سیستمی و الزامات پلتفرم است. CocoaPods podspec را با اعتبارسنجی pod spec lint قبل از انتشار در رجیستر بررسی می‌کند.

Pod::Spec.new do |s|
  s.name             = 'NetworkingKit'
  s.version          = '1.2.0'
  s.summary          = 'Lightweight HTTP client for iOS'
  s.description      = 'NetworkingKit is a Swift HTTP client with async/await support, built-in caching, and automatic retry logic.'
  s.homepage         = 'https://github.com/user/NetworkingKit'
  s.license          = { :type => 'MIT', :file => 'LICENSE' }
  s.author           = { 'Developer' => 'dev@example.com' }
  s.source           = { :git => 'https://github.com/user/NetworkingKit.git', :tag => s.version.to_s }
  s.ios.deployment_target = '15.0'
  s.swift_version    = '5.9'
  s.source_files     = 'Sources/**/*.swift'
  s.dependency 'Alamofire', '~> 5.9'
end

s.name — نام منحصربه‌فرد کتابخانه در رجیستر. s.version مطابق با تگ Git است (برای انتشار مهم است). s.source_files — الگوی glob برای گنجاندن فایل‌های منبع. s.dependency وابستگی به podهای دیگر را با نسخه مشخص می‌کند. s.ios.deployment_target حداقل نسخه پشتیبانی شده iOS را تعیین می‌کند — CocoaPods به طور خودکار هشدار می‌دهد اگر پروژه از نسخه قدیمی‌تر استفاده کند. برای podهای خصوصی می‌توان از :path در Podfile به جای انتشار در رجیستر استفاده کرد.

انتشار کتابخانه در رجیستر مرکزی Specs از طریق pod trunk push NetworkingKit.podspec انجام می‌شود. ثبت‌نام قبلی از طریق pod trunk register dev@example.com 'Developer' لازم است. CocoaPods اعتبار podspec را بررسی کرده و یک pull request به مخزن Specs ارسال می‌کند. جایگزین — رجیستر خصوصی pod repo push برای کتابخانه‌های داخلی شرکت است.

Subspecs و ماژولار بودن

Subspecs امکان تقسیم کتابخانه به ماژول‌هایی را فراهم می‌کند که کاربر می‌تواند به صورت انتخابی متصل کند. به عنوان مثال، Firebase از subspecs استفاده می‌کند: pod 'Firebase/Crashlytics' فقط Crashlytics را بدون سایر ماژول‌های Firebase متصل می‌کند. Subspec پیکربندی پایه را به ارث برده و می‌تواند source_files و وابستگی‌های خود را اضافه کند.

نصب و پیکربندی CocoaPods

CocoaPods از طریق RubyGems — مدیر بسته استاندارد Ruby نصب می‌شود. در macOS، Ruby از قبل نصب شده است، بنابراین یک دستور در ترمینال کافی است. روش جایگزین Homebrew است که CocoaPods را به عنوان یک فرمول جداگانه نصب می‌کند. پس از نصب، مقداردهی اولیه پروژه با دستور pod init انجام می‌شود که Podfile را با پیکربندی پایه ایجاد می‌کند. پس از پر کردن Podfile با وابستگی‌ها، توسعه‌دهنده pod install را اجرا می‌کند — CocoaPods کتابخانه‌ها را بارگیری کرده و فضای کاری را تولید می‌کند.

# نصب CocoaPods از طریق RubyGems
sudo gem install cocoapods

# نصب جایگزین از طریق Homebrew
brew install cocoapods

# مقداردهی اولیه Podfile در پروژه
cd /path/to/Project
pod init

# نصب وابستگی‌ها
pod install

قانون مهم: پس از pod install همیشه .xcworkspace را باز کنید، نه .xcodeproj را. اگر .xcodeproj را باز کنید، Xcode podها را نمی‌بیند و ساخت با خطاهای linking مواجه می‌شود. دستور pod install وابستگی‌ها را فقط در صورت تغییر Podfile یا در اولین اجرا بارگیری می‌کند. برای نصب مجدد اجباری همه podها از pod install --repo-update یا pod deintegrate && pod install استفاده می‌شود.

به‌روزرسانی CocoaPods از طریق sudo gem update cocoapods یا brew upgrade cocoapods انجام می‌شود. نسخه CocoaPods با دستور pod --version بررسی می‌شود. از نسخه ۱٫۱۲ (۲۰۲۴)، CocoaPods از Xcode ۱۵ با تنظیمات بررسی دقیق ماژول‌ها و حل بهبود یافته وابستگی‌های انتقالی پشتیبانی می‌کند. آخرین نسخه پایدار در mid-2025 نسخه ۱٫۱۶ با پشتیبانی از Swift ۶ و عملکرد بهبود یافته حل گراف وابستگی برای پروژه‌های با ۵۰+ pod است.

# به‌روزرسانی همه podها به آخرین نسخه‌ها
pod update

# به‌روزرسانی pod خاص
pod update Alamofire

# بررسی وابستگی‌های منسوخ
pod outdated

# حذف CocoaPods از پروژه
pod deintegrate

pod update بدون آرگومان همه podها را به آخرین نسخه‌های سازگار طبق Podfile به‌روزرسانی می‌کند (با در نظر گرفتن عملگرهای ~>). pod outdated تفاوت بین نسخه فعلی در Podfile.lock و آخرین نسخه موجود را نشان می‌دهد. pod deintegrate CocoaPods را به طور کامل از پروژه حذف می‌کند — .xcworkspace، فایل‌های پیکربندی و تنظیمات ساخت را حذف می‌کند. این برای مهاجرت به Swift Package Manager مفید است.

مدیریت وابستگی‌ها و نسخه‌ها

مدیریت وابستگی‌ها در CocoaPods شامل چهار جنبه است: ثابت‌سازی نسخه، حل تداخل، بهینه‌سازی ساخت و کار با وابستگی‌های انتقالی. CocoaPods یک گراف وابستگی بر اساس Podfile.lock می‌سازد — اگر در پروژه از کتابخانه‌های A و B استفاده شود که هر دو به C وابسته هستند، CocoaPods نسخه‌ای از C را پیدا می‌کند که نیازهای هر دو را برآورده کند.

تداخل‌ها زمانی رخ می‌دهند که دو وابستگی نسخه‌های ناسازگاری از یک کتابخانه را نیاز دارند. CocoaPods با نشان دادن نیازهای متضاد خطا گزارش می‌دهد. راه‌حل‌ها: به‌روزرسانی یکی از وابستگی‌ها به نسخه سازگار، استفاده از pod 'Lib', :git => ... با تعیین commit خاص یا fork کردن یکی از کتابخانه‌ها با وابستگی تغییر یافته. برای پروژه‌های بزرگ، توصیه می‌شود اعتبارسنجی CI با pod lib lint در هر درخواست pull پیکربندی شود.

استراتژی‌های مدیریت پیشرفته

CocoaPods چندین قابلیت پیشرفته ارائه می‌دهد: :path برای توسعه محلی کتابخانه‌ها، :git برای اتصال forkها، :branch برای تست شاخه‌های توسعه. دستور use_frameworks! با :linkage => :static اندازه فایل باینری نهایی را به حداقل می‌رساند. برای تست A/B و feature flagها می‌توان نسخه‌های مختلف podها را از طریق ساختارهای شرطی Ruby در Podfile متصل کرد.

platform :ios, '15.0'
use_frameworks!

# تعیین محیط
is_debug = defined?(DEBUG) && DEBUG

target 'MyApp' do
  # وابستگی‌های اصلی
  pod 'Alamofire', '~> 5.9'
  pod 'SnapKit', '~> 5.7'

  # کتابخانه محلی برای توسعه
  pod 'MyInternalLib', :path => '../MyInternalLib'

  # وابستگی شرطی برای اشکال‌زدایی
  if is_debug
    pod 'SwiftyBeaver', '~> 2.0'
  else
    pod 'CocoaLumberjack', '~> 3.8'
  end

  # فورک با رفع باگ
  pod 'Kingfisher', :git => 'https://github.com/user/Kingfisher.git', :branch => 'fix-memory-leak'
end

abstract_target 'Pods' do
  pod 'Alamofire'
end

abstract_target یک target مجازی برای وابستگی‌های مشترک بدون اتصال به target خاص Xcode ایجاد می‌کند. ساختارهای شرطی Ruby امکان اتصال کتابخانه‌های مختلف برای پیکربندی‌های Debug و Release را فراهم می‌کنند. :path با کتابخانه محلی توسعه را سرعت می‌بخشد — تغییرات بدون راه‌اندازی مجدد pod install اعمال می‌شوند. حالت :branch برای تست تغییرات قبل از انتشار رسمی مفید است.

CocoaPods در مقابل Swift Package Manager در مقابل Carthage

CocoaPods، Swift Package Manager (SPM) و Carthage — سه مدیر وابستگی اصلی در توسعه iOS هستند. هر کدام معماری، رویکرد یکپارچه‌سازی و سطح کنترل خاص خود را دارند. CocoaPods از نظر تعداد کتابخانه‌ها پیشرو است، SPM به دلیل پشتیبانی داخلی در Xcode برنده است، Carthage از نظر محبوبیت عقب‌تر است اما حداکثر کنترل را می‌دهد.

CocoaPods انتخاب پروژه‌هایی است که به حداکثر سازگاری با کتابخانه‌ها نیاز دارند (بسیاری از کتابخانه‌های legacy فقط از طریق CocoaPods در دسترس هستند). SPM برای پروژه‌های جدید توصیه می‌شود — در Xcode تعبیه شده، نیاز به نصب ابزارهای اضافی ندارد و توسط Apple پشتیبانی می‌شود. Carthage به ندرت استفاده می‌شود، عمدتاً در پروژه‌هایی با نیاز به حداقل دخالت در پیکربندی Xcode. از سال ۲۰۲۴، Apple به طور فعال SPM را توسعه می‌دهد و بسیاری از کتابخانه‌های محبوب (Alamofire, Firebase, SnapKit) در حال حاضر آن را در کنار CocoaPods پشتیبانی می‌کنند.

مهاجرت از CocoaPods به SPM از طریق pod deintegrate (حذف CocoaPods) و افزودن بسته‌ها از طریق File → Add Package Dependencies در Xcode انجام می‌شود. مشکلات اصلی: کتابخانه‌های دارای منابع (فونت‌ها، تصاویر، storyboard) ممکن است رفتار متفاوتی داشته باشند و پلاگین‌های CocoaPods (مثلاً برای تولید کد) در SPM مشابه ندارند. توصیه می‌شود CocoaPods را برای پروژه‌هایی که به قابلیت‌های خاص CocoaPods نیاز دارند نگه دارید: تولید کد، بسته‌های منبع و مراحل ساخت سفارشی از طریق هوک‌های post_install.

مشکلات رایج و راه‌حل‌ها

CocoaPods — ابزاری پایدار است، اما توسعه‌دهندگان گاهی با مشکلات معمولی مواجه می‌شوند. اکثر آنها به نسخه‌های Ruby، کش کردن یا تداخل وابستگی‌ها مربوط می‌شوند. در زیر رایج‌ترین سناریوها و راه‌حل‌ها آورده شده است.

خطای «The sandbox is not in sync with the Podfile.lock» — هنگام تغییر Podfile.lock در مخزن قبل از اجرای pod install رخ می‌دهد. راه‌حل: اجرای pod install یا pod deintegrate && pod install. برای محیط‌های CI توصیه می‌شود pod install را به اسکریپت ساخت اضافه کنید. یکی دیگر از دلایل رایج تفاوت نسخه CocoaPods بین توسعه‌دهندگان است: pod --version را در semua ماشین‌ها بررسی کنید.

خطا در به‌روزرسانی رجیستر Specs — معمولاً ناشی از مشکلات شبکه یا مخزن Git قدیمی است. راه‌حل: pod repo update --verbose جزئیات را نشان می‌دهد. اگر Specs خراب است: rm -rf ~/.cocoapods/repos/master && pod repo add master https://github.com/CocoaPods/Specs.git. در اینترنت کند می‌توان از CDN استفاده کرد — از CocoaPods ۱٫۸+ به طور پیش‌فرض فعال است.

خطای duplicate symbols — هنگام اتصال یک کتابخانه دو بار یا تداخل نمادها بین podها رخ می‌دهد. راه‌حل: Podfile را برای تکرار بررسی کنید، از use_frameworks! :linkage => :static برای جداسازی نمادها استفاده کنید. اگر مشکل در کتابخانه است — به نویسنده گزارش دهید. گاهی اوقات پاک کردن Derived Data و راه‌اندازی مجدد Xcode کمک می‌کند.

CocoaPods روی Apple Silicon Mac نصب نمی‌شود — Ruby از پیش نصب شده روی macOS از طریق Rosetta ۲ کار می‌کند که باعث خطاهای کامپایل می‌شود. راه‌حل: Ruby را از طریق rbenv یا asdf برای معماری بومی ARM64 نصب کنید. جایگزین — استفاده از Homebrew: brew install cocoapods به طور خودکار برای ARM64 کامپایل می‌شود. اگر gems برای x86_64 نصب شده باشند، دستور arch -arm64 sudo gem install cocoapods مشکل را حل می‌کند.

نصب کند podها — در پروژه‌های بزرگ pod install ممکن است دقیقه‌ها طول بکشد. راه‌حل: --verbose را برای تشخیص فعال کنید. اگر Specs از قبل به‌روز است از --no-repo-update استفاده کنید. برای سرورهای CI پوشه Pods/ و ~/.cocoapods را کش کنید. در CocoaPods ۱٫۱۲+ بارگیری موازی از طریق install! 'cocoapods', :parallel_download => true اضافه شده است.