pubspec.yaml — این چیست، ساختار و پیکربندی وابستگی‌ها در Flutter

pubspec.yaml چیست

pubspec.yaml — یک فایل مانیفست در قالب YAML است که مدیر بسته pub از آن برای مدیریت پروژه‌های Dart و Flutter استفاده می‌کند. این فایل در ریشه پروژه قرار دارد و با هر دستور flutter pub get پردازش می‌شود. برخلاف سایر پلتفرم‌ها که پیکربندی در چندین فایل پراکنده است، Flutter از یک مانیفست متمرکز برای همه نیازها استفاده می‌کند.

فایل شامل فراداده است: نام پروژه، توضیحات، نسخه، نویسنده. این داده‌ها هنگام انتشار بسته در pub.dev و هنگام ساخت برنامه برای App Store و Google Play استفاده می‌شوند. فیلد description در نتایج جستجوی بسته‌ها نمایش داده می‌شود، بنابراین باید informative باشد و شامل کلمات کلیدی باشد که دیگر توسعه‌دهندگان بتوانند کتابخانه را پیدا کنند.

بدون pubspec.yaml صحیح، پروژه Flutter نمی‌تواند ساخته شود. خطاهای نحوی یا تورفتگی‌های نادرست منجر به شکست فوری کامپایل با پیام Error on line X می‌شود. YAML به فاصله‌ها حساس است: یک فاصله اضافی ساختار داده را تغییر می‌دهد و tab باعث خطای نحوی می‌شود. بنابراین هنگام ویرایش دستی pubspec.yaml استفاده از ویرایشگری با برجسته‌سازی نحو YAML، مانند VS Code با افزونه رسمی Flutter، مهم است.

بخش‌های اصلی pubspec.yaml

pubspec.yaml از بخش‌های اجباری و اختیاری تشکیل شده است. هر بخش مسئول جنبه خاصی از پیکربندی پروژه است. ترتیب بخش‌ها مهم نیست، اما طبق قرارداد جامعه سلسله‌مراتب رعایت می‌شود: فراداده، محیط، وابستگی‌ها، منابع، پلتفرم‌ها.

name و description

فیلد name شناسه منحصربه‌فرد بسته را در قالب snake_case، متشکل از حروف کوچک لاتین، اعداد و زیرخط تعیین می‌کند. فیلد description — توضیح کوتاه پروژه تا ۱۸۰ کاراکتر، اجباری برای انتشار در pub.dev. توضیح باید هدف بسته را توضیح دهد، بدون تکرار نام، و شامل کلمات کلیدی برای بهینه‌سازی جستجوی مخزن باشد.

name: my_flutter_app
description: برنامه مدیریت وظایف با Flutter
publish_to: 'none'

version و environment

فیلد version از نسخه‌بندی معنایی major.minor.patch با شماره ساخت اختیاری بعد از علامت مثبت (1.0.0+1) استفاده می‌کند. بخش environment حداقل و حداکثر نسخه‌های Dart و Flutter SDK را برای تضمین سازگاری تعیین می‌کند. اگر نسخه جدید 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

پیکربندی assets و فونت‌ها

بخش 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

اتصال assets از طریق pubspec.yaml فایل‌ها را از طریق AssetBundle در زمان اجرا در دسترس قرار می‌دهد. این برای تصاویر، JSON، فایل‌های متنی و هر منبع دیگری کار می‌کند. Flutter به طور خودکار از وضوح‌های مختلف صفحه پشتیبانی می‌کند: اگر images/2x/ و images/3x/ قرار دهید، Flutter نسخه مناسب تصویر را بر اساس device pixel ratio دستگاه انتخاب می‌کند. برای این کار کافی است در assets فقط پوشه ریشه images/ را مشخص کنید.

فونت‌های سفارشی از طریق بخش fonts با مشخص کردن family و لیست قلم‌ها اضافه می‌شوند. پس از تغییر pubspec.yaml باید flutter pub get را اجرا کنید تا تنظیمات اعمال شوند. فونت‌ها را می‌توان هم به صورت سراسری در تم MaterialApp و هم به صورت محلی در ویجت‌های خاص استفاده کرد. برای هر قلم می‌توان weight (100-900) و style (normal, italic) را مشخص کرد که به Flutter اجازه می‌دهد هنگام استفاده از FontWeight و FontStyle در کد، فایل فونت را به درستی انتخاب کند.

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

pub از چندین روش برای مشخص کردن منابع وابستگی‌ها پشتیبانی می‌کند: pub.dev، مخازن Git، مسیرهای محلی و مخازن خصوصی. انتخاب منبع به مرحله توسعه بستگی دارد: برای نسخه‌های پایدار از pub.dev، برای forkها و تغییرات سفارشی — 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 فقط به طور موقت برای حل تعارضات یا آزمایش نسخه‌های جدید استفاده کنید. پس از رفع وابستگی‌های اصلی، override باید حذف شود تا گراف وابستگی پروژه در بلندمدت مختل نشود.

بخش executables در pubspec.yaml امکان مشخص کردن اسکریپت‌های اجرایی را فراهم می‌کند که pub هنگام فعال‌سازی بسته در PATH نصب می‌کند. این برای ابزارهای CLI نوشته شده با Dart، مانند build_runner یا dart_code_metrics مفید است. دستور dart pub global activate بسته را به صورت سراسری نصب می‌کند و اسکریپت‌های مشخص شده در executables را از ترمینال در دسترس قرار می‌دهد. برای برنامه‌ها معمولاً از executables استفاده نمی‌شود، زیرا نقطه ورود از طریق main در lib/main.dart تعیین می‌شود.