ترحيل Flutter iOS من CocoaPods إلى Swift Package Manager مع Firebase: دليل آمن للمشاريع الحالية

توقفت Firebase خلال أكتوبر 2026 عن نشر الإصدارات الجديدة من حزم Apple عبر CocoaPods. الإصدارات الموجودة لن تختفي، والتطبيقات المبنية بها لن تتعطل فجأة، لكن المشروع الذي يبقى عليها لن يحصل عبر CocoaPods على أحدث ميزات Firebase وإصلاحاته وتحسيناته. وفي الوقت نفسه، أصبح Swift Package Manager هو المسار الافتراضي لإدارة تبعيات iOS وmacOS في Flutter 3.44.

هذا لا يعني أن تحذف Podfile فورًا. مشاريع Flutter الحقيقية قد تضم إضافات لم تنتقل بعد إلى SwiftPM، أو إعدادات يدوية لـCrashlytics، أو SDK دفع واتصال يعتمد على CocoaPods. المطلوب ترحيل قابل للرجوع يبدأ بالجرد وينتهي ببناء نظيف واختبار نسخة فعلية.

ما الذي تغيّر، وما الذي لم يتغير؟

توضح Firebase رسميًا أن CocoaPods سيتحول إلى سجل للقراءة فقط في ديسمبر 2026، وأن Firebase أوقفت نشر إصدارات جديدة إليه في أكتوبر. ستظل الإصدارات القديمة متاحة، لذلك لا يوجد انقطاع فوري. لكن الاستمرار عليها يجمد طبقة Apple الأصلية التي تعتمد عليها إضافات Firebase.

من جانب Flutter، توضح وثائق SwiftPM أن الدعم أصبح مفعّلًا افتراضيًا ابتداءً من Flutter 3.44. عند ترقية Flutter وتشغيل المشروع، يضيف Flutter التكامل اللازم ويحمّل حزم Swift التي تعلنها الإضافات. وإذا وُجدت إضافة لا تدعم SwiftPM، يعود Flutter إلى CocoaPods تلقائيًا.

إذًا هناك حالتان مختلفتان:

• تطبيق Flutter يستخدم FlutterFire فقط: راقب دعم الإضافات لـSwiftPM ودع Flutter يدير التبعيات الأصلية.
• تطبيق يضيف Firebase يدويًا داخل iOS أو يحتوي native targets: تحتاج أيضًا إلى نقل تبعيات Firebase الأصلية إلى SwiftPM داخل Xcode.

الخلط بين الحالتين قد يؤدي إلى إضافة Firebase مرتين أو حذف إعداد يحتاجه Plugin آخر.

لماذا يهم هذا لتطبيق منتج أو MVP؟

مدير الحزم جزء من سلسلة الإصدار، لا مجرد تفضيل تنظيمي. خطأ في الانتقال يمكن أن يظهر في صورة:

• بناء ناجح محليًا وفاشل على CI بسبب اختلاف Xcode أو cache؛
• رموز dSYM غير مرفوعة إلى Crashlytics؛
• إضافة Flutter تعمل على Android وتفشل عند الربط على iOS؛
• اختلاف في الحد الأدنى لإصدار iOS؛
• تضاعف رموز أو frameworks بسبب وجود CocoaPods وSwiftPM للتبعية نفسها.

لذلك يجب التعامل مع الترحيل كتغيير بنية إصدار، مع Pull Request مستقل ونتائج قابلة للمراجعة.

خطة الترحيل خطوة بخطوة

1. ثبّت خط أساس قبل التعديل

ابدأ من فرع نظيف وسجّل إصدارات الأدوات المستخدمة:

bashflutter --version
dart --version
xcodebuild -version
pod --version
flutter doctor -v

نفّذ بناء iOS واختبارات المشروع الحالية، واحفظ سجلًا لنسخة ناجحة. إذا كان التطبيق يستخدم تسجيل الدخول، والإشعارات، وCrashlytics، وRemote Config، فاكتب مسارات smoke قصيرة لكل منها. الهدف هو معرفة ما إذا كان الخلل ظهر بعد الترحيل بالفعل.

2. اجرد التبعيات الأصلية

راجع هذه الأماكن:

• pubspec.yaml لإضافات Flutter؛
• ios/Podfile لأي Pods أو hooks أو build settings أضيفت يدويًا؛
• ios/Podfile.lock لمعرفة التبعيات الحالية؛
• Xcode > Package Dependencies لأي حزم Swift موجودة بالفعل؛
• Build Phases، خصوصًا سكربتات Crashlytics؛
• إعدادات CI التي تنفذ pod install أو تحفظ Pods في cache.

صنّف كل عنصر إلى: يدعم SwiftPM، يحتاج CocoaPods مؤقتًا، أو مضاف يدويًا ويحتاج قرارًا. لا تفترض أن كل Pod جاء من FlutterFire.

3. رقِّ Flutter والإضافات في تغيير محدود

استخدم نسخة Flutter مستقرة تدعم SwiftPM افتراضيًا، ثم حدّث الإضافات بعد قراءة changelog لكل حزمة. لا تجمع في Pull Request نفسه إعادة تصميم معماري أو تحديثات واسعة غير مرتبطة؛ فصل التغييرات يجعل التشخيص والتراجع أسهل.

بعد flutter pub get، شغّل المشروع من Xcode وتحقق من وجود FlutterGeneratedPluginSwiftPackage كـtarget dependency ومن تنفيذ Run Prepare Flutter Framework Script كـpre-action، وفق فحص Flutter الرسمي.

4. لا تحذف CocoaPods حتى تختفي أسباب الرجوع إليه

تقول وثائق Flutter صراحة إنه يعود إلى CocoaPods إذا كانت أي تبعية لا تدعم SwiftPM. لذلك وجود Podfile بعد الترقية لا يعني أن الترحيل فشل. قد يكون مشروعك في مرحلة مختلطة صحيحة.

احذف تكامل CocoaPods فقط عندما:

1. كل إضافات المشروع تدعم SwiftPM؛
2. لا توجد Pods يدوية لازمة؛
3. نُقلت أي إعدادات مخصصة في Podfile إلى البديل الصحيح؛
4. نجح البناء والاختبار على جهاز أو Simulator وعلى CI.

إذا كنت تضيف Firebase الأصلي مباشرة، اتبع طريقة التثبيت الرسمية: أضف مستودع firebase-ios-sdk من Xcode واختر المنتجات المطلوبة فقط. لا تضف SDK الأصلي يدويًا إذا كانت إضافة Flutter تديره بالفعل إلا لسبب موثق.

5. راجع الحالات الخاصة

Crashlytics

لا يكفي أن ينجح الربط. تحقق من سكربت رفع dSYM ومكانه بعد انتقال الحزمة إلى SourcePackages. توثيق Firebase يعرض مسار السكربت الخاص بتوزيع SwiftPM. اختبر crash غير إنتاجي وفق دليل Firebase وتأكد من وصوله قبل الدمج.

Analytics

إذا وصلت Analytics بصورة transitively، قد تحتاج إلى علم الربط -ObjC وفق طريقة دمج Firebase. راجع الإعداد الحالي بدل إضافة العلم عشوائيًا.

الحد الأدنى لـiOS

قد تتطلب إحدى حزم Swift أو إضافات Flutter حدًا أعلى للنظام. لا ترفع Deployment Target تلقائيًا قبل معرفة أثره في الأجهزة المدعومة. Flutter يعرض رسالة واضحة عندما يكون الحد أقل من المطلوب.

SDKs غير Firebase

قد يظل SDK دفع أو خرائط أو VoIP معتمدًا على CocoaPods. SwiftPM وCocoaPods يمكن أن يتعايشا أثناء الانتقال، لكن لا تسمح بإدارة المكتبة نفسها من الاثنين.

6. حدّث CI والـcache

راجع pipeline بدل حذف pod install مباشرة. إذا بقي fallback واحد إلى CocoaPods فسيظل الأمر مطلوبًا. في المسار المعتمد على SwiftPM:

• ثبّت نسخة Flutter وXcode بدل الاعتماد على أحدث نسخة عشوائيًا؛
• نفّذ بناءً نظيفًا مرة واحدة للتأكد من عدم اعتماد النجاح على cache قديم؛
• احفظ Package.resolved وفق سياسة الفريق لتثبيت الإصدارات؛
• اضبط cache لحزم Swift من دون مشاركة مخرجات غير متوافقة بين نسخ Xcode؛
• احتفظ بالسجلات ونتائج الاختبار كـartifacts.

بوابة تحقق قبل الدمج

استخدم قائمة قصيرة قابلة للإثبات:

هذه القائمة تحليل هندسي مقترح، وليست ضمانًا بأن كل Plugin خارجي متوافق. المصدر النهائي لدعم أي إضافة هو توثيقها وإصدارها المستخدم.

الخلاصة

توقف Firebase عن نشر تحديثات CocoaPods لا يكسر تطبيقك اليوم، لكنه يحول البقاء الدائم إلى دين تقني. في Flutter 3.44 وما بعده، ابدأ بتفعيل SwiftPM وفحص التبعيات، واترك fallback يعمل مؤقتًا، ثم أزل CocoaPods فقط عندما تثبت أن كل إضافة وCI ومسار Firebase يعمل من دونها.

إذا كنت تبني تطبيق أعمال أو MVP وتحتاج مراجعة بنية Flutter وخط إصدار iOS قبل التسليم، يمكنك الاطلاع على خدمة تطوير MVP أو تطوير تطبيق ومنصة للأعمال. القرار الصحيح هنا يحمي قابلية تحديث المنتج، لكنه لا يضمن ترتيبًا في البحث أو جودة المنتج وحده؛ هذه تُقاس باختبارات ومراقبة فعلية بعد الإصدار.

المصادر

• Firebase رسميًا
• وثائق SwiftPM
• طريقة التثبيت الرسمية