pubspec.yaml — ما هو، هيكله وتكوين التبعيات في Flutter

ما هو pubspec.yaml

pubspec.yaml هو ملف بيان بتنسيق YAML يستخدمه مدير الحزم pub لإدارة مشاريع Dart وFlutter. يقع في جذر المشروع وتتم معالجته مع كل أمر flutter pub get. على عكس المنصات الأخرى حيث يكون التكوين موزعاً عبر عدة ملفات، يستخدم Flutter بياناً مركزياً واحداً لجميع الاحتياجات.

يحتوي الملف على بيانات وصفية: اسم المشروع، الوصف، الإصدار، المؤلف. تُستخدم هذه البيانات عند نشر حزمة على pub.dev وعند بناء التطبيق لـ App Store وGoogle Play. يُعرض حقل description في نتائج بحث الحزم، لذا يجب أن يكون غنياً بالمعلومات ويحتوي على كلمات رئيسية يمكن للمطورين الآخرين استخدامها للعثور على المكتبة.

بدون pubspec.yaml صحيح، لا يمكن بناء مشروع Flutter. تؤدي أخطاء بناء الجملة أو المسافة البادئة غير الصحيحة إلى فشل فوري في الترجمة مع رسالة خطأ في السطر X. YAML حساس للمسافات البيضاء: مسافة إضافية واحدة تغير بنية البيانات، وتسبب علامات التبويب خطأ في بناء الجملة. لذلك، عند تحرير pubspec.yaml يدوياً، من المهم استخدام محرر مع تمييز بناء جملة YAML، مثل VS Code مع الإضافة الرسمية لـ Flutter.

الأقسام الرئيسية لـ pubspec.yaml

يتكون pubspec.yaml من أقسام إلزامية واختيارية. كل قسم مسؤول عن جانب معين من تكوين المشروع. ترتيب الأقسام غير مهم، ولكن وفقاً لاتفاقية المجتمع، يتم اتباع التسلسل الهرمي: البيانات الوصفية، البيئة، التبعيات، الموارد، المنصات.

name و description

حقل name يحدد معرفاً فريداً للحزمة بتنسيق snake_case، يتكون فقط من أحرف لاتينية صغيرة وأرقام وشرطات سفلية. حقل description هو ملخص موجز للمشروع يصل إلى 180 حرفاً، وهو إلزامي للنشر على pub.dev. يجب أن يشرح الوصف الغرض من الحزمة دون تكرار الاسم، وأن يحتوي على كلمات رئيسية لتحسين محركات البحث في المستودع.

name: my_flutter_app
description: تطبيق لإدارة المهام مع Flutter
publish_to: 'none'

version و environment

حقل version يستخدم التحكم الدلالي في الإصدارات major.minor.patch مع رقم بناء اختياري بعد علامة الجمع (1.0.0+1). يحدد قسم environment الحد الأدنى والأقصى لإصدارات SDK الخاصة بـ Dart وFlutter لضمان التوافق. إذا كان الإصدار الجديد من SDK يحتوي على تغييرات جذرية غير متوافقة مع كود المشروع، فسيتوقف البناء مع رسالة خطأ واضحة.

version: 1.0.0+1
environment:
  sdk: '>=3.2.0 <4.0.0'
  flutter: '>=3.16.0'

dependencies و dev_dependencies

يسرد قسم dependencies الحزم اللازمة لتشغيل التطبيق في وقت التشغيل. يحتوي قسم dev_dependencies على حزم للاختبار وتوليد الكود والتطوير — وهي غير مضمنة في بناء الإصدار النهائي. فصل التبعيات أمر بالغ الأهمية للأداء: كل حزمة في dependencies تزيد من حجم APK أو IPA النهائي، وكذلك وقت بدء تشغيل التطبيق بسبب تهيئة المكتبات الإضافية.

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0
  provider: ^6.1.0
  shared_preferences: ^2.2.0
  cached_network_image: ^3.3.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  mockito: ^5.4.0
  build_runner: ^2.4.0

تكوين الأصول والخطوط

يحتوي قسم flutter على أقسام فرعية لتكوين الموارد والخطوط ومعلمات المنصة. تُوصَل الموارد من خلال مصفوفة paths تحدد ملفات معينة أو أدلة كاملة. تُحدد جميع المسارات بالنسبة لجذر المشروع، وليس بالنسبة لـ pubspec.yaml. هذا فارق مهم غالباً ما يسبب ارتباكاً لمطوري Flutter المبتدئين.

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/icons/
    - assets/config.json
    - assets/data/translations/
  fonts:
    - family: RobotoMono
      fonts:
        - asset: fonts/RobotoMono-Regular.ttf
        - asset: fonts/RobotoMono-Bold.ttf
          weight: 700
        - asset: fonts/RobotoMono-Italic.ttf
          style: italic

ربط الأصول من خلال pubspec.yaml يجعل الملفات قابلة للوصول عبر AssetBundle في وقت التشغيل. يعمل هذا مع الصور وملفات JSON والملفات النصية وأي موارد أخرى. يدعم Flutter تلقائياً دقات الشاشة المختلفة: إذا أضفت images/2x/ و images/3x/، سيختار Flutter إصدار الصورة المناسب بناءً على نسبة البكسل في الجهاز. للقيام بذلك، يكفي تحديد مجلد images/ الجذر فقط في assets.

تُضاف الخطوط المخصصة من خلال قسم fonts مع اسم العائلة وقائمة الأنماط. بعد تعديل pubspec.yaml، تحتاج إلى تنفيذ flutter pub get لتطبيق التغييرات. يمكن استخدام الخطوط عالمياً في سمة MaterialApp أو محلياً في أدوات واجهة محددة. لكل نمط، يمكن تحديد weight (100–900) و style (normal, italic)، مما يسمح لـ Flutter بتحديد ملف الخط الصحيح عند استخدام FontWeight و FontStyle في الكود.

إدارة التبعيات والإصدارات

يدعم pub عدة طرق لتحديد مصادر التبعيات: pub.dev، مستودعات Git، المسارات المحلية والمستودعات الخاصة. يعتمد اختيار المصدر على مرحلة التطوير: للإصدارات المستقرة يُستخدم pub.dev، للتفرعات والتعديلات المخصصة — Git، للمكتبات التي يتم تطويرها بالتوازي — المسار المحلي.

عامل ^version يعني إصداراً متوافقاً: ^1.2.0 يسمح بالإصدارات >=1.2.0 و <2.0.0. هذا مشابه للعامل ~> في CocoaPods وعامل Caret في npm. يقوم pub تلقائياً بحل Dependency Hell من خلال خوارزمية SAT solver التي تجد مجموعة من الإصدارات تلبي جميع القيود. إذا لم توجد مثل هذه المجموعة، يُخرج pub رسالة مفصلة تشير إلى الحزم المتعارضة.

ملف pubspec.lock يثبت الإصدارات الدقيقة للتبعيات. يجب تخزينه في نظام التحكم في الإصدارات للتطبيقات لضمان بناءات قابلة للتكرار على جميع أجهزة الفريق. بالنسبة للمكتبات، لا يتم تضمين pubspec.lock في المستودع، لأن مستخدمي المكتبة يجب أن يكونوا قادرين على استخدامها مع إصدارات مختلفة من التبعيات. أمر flutter pub upgrade يحدث جميع التبعيات وفقاً لقيود pubspec.yaml، بينما flutter pub outdated يعرض الحزم التي يمكن تحديثها.

تكوين البناء والنشر

لنشر تطبيق على pub.dev، يتم تحديد الإعدادات في قسم publish_to. القيمة 'none' تمنع النشر العرضي للحزمة، وهو أمر مهم للمشاريع الداخلية أو غير العامة. إذا كان publish_to مفقوداً، يحاول pub نشر الحزمة على pub.dev الافتراضي، مما قد يؤدي إلى تسرب غير مرغوب فيه للكود.

يتضمن قسم flutter معلمات المنصة: generate للتوليد التلقائي لملفات المنصة، و deferred-components للتحميل المعياري للوظائف. المعلمة generate: true تجبر Flutter على إنشاء وتحديث مشاريع المنصة (iOS، Android، Web) تلقائياً عند إضافة منصات جديدة عبر flutter create --platforms. بدون هذه المعلمة، قد يصبح هيكل مجلدات المنصة غير متزامن مع pubspec.yaml.

flutter:
  generate: true
  deferred-components:
    - name: photoEditor
      libraries:
        - package:photo_editor/library.dart

يقوم قسم platforms بتعيين المنصات المستهدفة للحزمة. للتطبيقات، يتم تحديده تلقائياً عند إضافة دعم لمنصة معينة عبر flutter create. يمكن إضافة المنصات وإزالتها يدوياً عن طريق تحرير pubspec.yaml. تسمح Deferred Components بتحميل أجزاء من التطبيق حسب الطلب، مما يقلل حجم التثبيت — وهذا مهم بشكل خاص للألعاب والتطبيقات التي تحتوي على كمية كبيرة من المحتوى نادر الاستخدام.

عند نشر حزمة، يتحقق pub من جميع حقول pubspec.yaml للتوافق مع متطلبات المستودع. يؤدي عدم وجود الحقول الإلزامية name و version و description إلى رفض النشر. بالإضافة إلى ذلك، يتم التحقق من صحة الترخيص ووجود README.md و CHANGELOG.md. الحزم التي تحتوي على أخطاء في محلل الكود (dart analyze) تفشل أيضاً في التحقق. بعد النشر الناجح، تصبح الحزمة متاحة على pub.dev في غضون دقائق.

يسمح قسم dependency_overrides بفرض إصدار حزمة معين، متجاهلاً القيود من التبعيات غير المباشرة. هذه آلية قوية لكنها خطيرة: إذا استخدمت بشكل غير صحيح، فقد تؤدي إلى عدم توافق المكتبات. استخدم dependency_overrides فقط بشكل مؤقت لحل النزاعات أو اختبار إصدارات جديدة. بعد إصلاح التبعيات الرئيسية، يجب إزالة التجاوز لتجنب كسر رسم بياني للتبعيات الخاص بالمشروع على المدى الطويل.

يسمح قسم executables في pubspec.yaml بتحديد نصوص قابلة للتنفيذ يقوم pub بتثبيتها في PATH عند تنشيط الحزمة. هذا مفيد لأدوات CLI المكتوبة بلغة Dart، مثل build_runner أو dart_code_metrics. أمر dart pub global activate يثبت الحزمة عالمياً، مما يجعل النصوص المحددة في executables متاحة من الطرفية. للتطبيقات، لا تُستخدم executables عادةً، حيث يتم تحديد نقطة الدخول من خلال main في lib/main.dart.