شارك المقالة
شرح flavorpilot لإعداد Flutter Flavors على Android وiOS

شرح flavorpilot لإعداد Flutter Flavors على Android وiOS

تخيل أن فريق الاختبار يحتاج نسخة من تطبيق Flutter تتصل بسيرفر تجريبي، بينما نسخة المتجر تستخدم سيرفر الإنتاج. وتريد تثبيت…

تخيل أن فريق الاختبار يحتاج نسخة من تطبيق Flutter تتصل بسيرفر تجريبي، بينما نسخة المتجر تستخدم سيرفر الإنتاج. وتريد تثبيت النسختين على نفس الهاتف، باسم مختلف لكل واحدة، من غير ما تبدّل رابط الـ API يدويًا قبل كل Build.

هنا يأتي دور Flutter Flavors. الفكرة أنك تحتفظ بمشروع واحد وتبني منه نسخًا مثل development وstaging وproduction. لكن إعداد Gradle وXcode يدويًا لكل نسخة يحتاج أكثر من خطوة، وأحيانًا لا تكتشف أن أحد الإعدادات ناقص إلا وقت البناء.

في هذا المقال سنستخدم flavorpilot، وهي أداة سطر أوامر لإعداد بيئات Flutter على Android وiOS من ملف واحد، ثم تشغيلها وبنائها بأوامر قصيرة.

ما الذي يضبطه flavorpilot في مشروع Flutter؟

  • Android: يضيف productFlavors إلى Gradle ويضبط اسم التطبيق ومعرّف الحزمة لكل بيئة.
  • iOS: يضيف Xcode Schemes وإعدادات البناء لكل بيئة، ويربطها بمعرّف الحزمة واسم العرض المناسبين.
  • Dart: يولّد lib/flavors.dart لتقرأ البيئة الحالية وإعداداتها من الكود.
  • أدوات التطوير: يضيف إعدادات تشغيل للبيئات في VS Code وAndroid Studio.

1. تثبيت flavorpilot وتهيئة المشروع

تحتاج إلى Flutter مع Dart 3.8 أو أحدث، ومشروع ببنية Flutter المعتادة. لبناء نسخة iOS ستحتاج إلى macOS وXcode. احفظ تغييراتك في Git قبل البداية، لأن التهيئة تعدّل ملفات المنصتين. بعد ذلك افتح الطرفية في المجلد الذي يحتوي على pubspec.yaml:

dart pub global activate flavorpilot
flavorpilot --version
flavorpilot init

يسألك init عن اسم التطبيق ومعرّفه الأساسي والبيئات المطلوبة. في مثالنا نستخدم development وstaging وproduction، ونختار لها الاختصارات dev وstg وprod. خلّي نسخة الإنتاج تحتفظ بمعرّف التطبيق الحالي، واستخدم مثلًا لاحقتي .dev و.stg للنسخ الداخلية حتى تقدر تثبّت النسخ جنب بعض.

إذا كانت البيئات تشترك في خطوات بدء التشغيل، اختر ملف main.dart واحدًا. ويمكن اختيار ملف دخول منفصل لكل بيئة عندما تختلف تهيئتها. الأداة لا تعدّل ملف lib/main.dart الحالي، لذلك ستضيف أنت منطق قراءة الإعدادات في المكان المناسب.

2. ضبط رابط API مختلف لكل بيئة

افتح flavorpilot.yaml وعدّل قسم env تحت كل بيئة. المقتطف التالي يوضح الجزء المطلوب إضافته أو تعديله داخل flavors؛ احتفظ بمعرّفات الحزم وأسماء التطبيقات التي كتبها init في ملفك:

flavors:
  development:
    env:
      base_url: https://dev.example.net
      enable_logs: true
  staging:
    env:
      base_url: https://staging.example.net
      enable_logs: true
  production:
    env:
      base_url: https://api.example.net
      enable_logs: false

استخدم نفس المفاتيح ونوع القيمة نفسه في كل البيئات. مثلًا، اكتب false دون علامات اقتباس ليبقى قيمة منطقية. استبدل الروابط التجريبية بروابط مشروعك، ثم طبّق الإعدادات وافحصها:

flavorpilot sync
flavorpilot doctor

بعد المزامنة، يقدر كود Dart يقرأ رابط البيئة الحالية من AppFlavor. لو عندك عميل HTTP بالفعل، مرّر له ناتج الدالة التالية وقت تهيئته:

import 'flavors.dart';

Uri currentApiBaseUri() {
  final flavor = AppFlavor.current;
  return Uri.parse(flavor.baseUrl);
}

شغّل التطبيق مع Flavor محدد. تشغيل flutter run وحده لن يحدد البيئة التي يعتمد عليها AppFlavor.current.

3. تشغيل بيئة الاختبار وبناء نسخة الإنتاج

flavorpilot run dev
flavorpilot run stg
flavorpilot build prod --target appbundle
flavorpilot build prod --target ipa

الأمر الثالث يبني ملف AAB لنسخة Android، والرابع يبني IPA على macOS بعد تجهيز التوقيع لمعرّف نسخة iOS. قبل رفع أي ملف إلى المتجر، تأكد من التوقيع ومعرّف الحزمة وأن التطبيق يتصل بعنوان الإنتاج الصحيح. إذا أردت إعداد بناء يزيد رقم الإصدار في pubspec.yaml، يمكنك استخدام flavorpilot release prod --target appbundle --bump patch؛ رفع الملف إلى المتجر خطوة منفصلة.

هل أضع مفاتيح API في ملف .env؟

يدعم flavorpilot ملفات منفصلة مثل .env.development عبر flavorpilot dotenv، ويمرر الملف المناسب إلى Flutter باستخدام --dart-define-from-file. تقرأ هذه القيم مثلًا باستخدام String.fromEnvironment. تجاهل الملف في Git يحميه من الظهور في المستودع، لكن القيمة تظل داخل التطبيق المبني. احتفظ بمفاتيح السيرفر وكلمات المرور على الخادم.

أخطاء شائعة قبل أول Build

  • الأمر غير موجود: أضف مجلد أدوات Dart العامة إلى PATH حسب المسار الذي يظهر بعد التثبيت.
  • المشروع لديه Flavors بالفعل: الأداة تتوقف عند إعدادات أصلية لم تنشئها. راجع دليل الترحيل واحفظ أسماء البيئات والمعرّفات الحالية قبل أي تعديل.
  • ملفات المشروع لم تتحدث: عدّل flavorpilot.yaml ثم نفّذ sync وراجع الفرق في Git، بدلًا من تحرير الأقسام التي تولّدها الأداة يدويًا.

الخلاصة

ابدأ بنسخة تطوير ونسخة إنتاج، وشغّل كل واحدة للتأكد من اسمها ومعرّفها ورابط الـ API. بعدها أضف Staging لو فريق الاختبار يحتاج بيئة مستقلة. وجود الإعدادات في ملف واحد يسهّل على الفريق مراجعة أي فرق بين النسخ قبل البناء.

للمزيد: توثيق flavorpilot على pub.dev ودليل Flutter لإعداد Flavors على Android.

شاهد أيضًا
مقالات ذات صلة
🚫 مانع الإعلانات مفعل

يجب إيقاف مانع الإعلانات لاستكمال تصفح الموقع