pub: مفاهیم کلیدی، مدیر بسته‌های Dart و pubspec.yaml

pub چیست؟

pub (Package Universal Browser) — مدیر بسته‌های داخلی است که به همراه Dart SDK ارائه می‌شود. این ابزار کتابخانه‌های خارجی را مدیریت می‌کند، تعارضات نسخه را حل می‌کند، وابستگی‌های گذرا را بارگیری می‌کند و بسته‌ها را به صورت محلی ذخیره می‌کند. در اکوسیستم Flutter از pub به عنوان ابزار اصلی برای اتصال پلاگین‌های ناوبری، کلاینت‌های HTTP، مدیران حالت و سایر مؤلفه‌ها استفاده می‌شود.

وظایف اصلی pub عبارتند از: نصب وابستگی‌ها از ثبت pub.dev، مسیرهای محلی (وابستگی‌های مسیر) و مخازن git؛ حل نسخه‌ها طبق قوانین نسخه‌بندی معنایی؛ ذخیره بسته‌های بارگیری شده در دایرکتوری سیستمی؛ انتشار بسته‌های شخصی در ثبت عمومی. همه این عملیات از طریق دستور CLI dart pub یا معادل flutter pub در دسترس هستند.

معماری pub بر گراف وابستگی بسته استوار است: مدیر درختی می‌سازد که در آن هر بسته دقیقاً یک بار وجود دارد. اگر دو کتابخانه نسخه‌های متفاوتی از یک بسته را نیاز داشته باشند، pub سعی می‌کند محدوده سازگاری پیدا کند یا خطای تعارض را گزارش می‌دهد. این با رویکرد npm که در آن نسخه‌های متعدد یک بسته در گره‌های مختلف درخت مجاز است، متفاوت می‌باشد.

ساختار pubspec.yaml

فایل pubspec.yaml — فایل مرکزی پیکربندی هر پروژه Dart یا Flutter است. این فایل به فرمت YAML نوشته می‌شود و شامل فراداده، وابستگی‌ها، پیکربندی ساخت و محدودیت‌های SDK می‌باشد. در زیر یک مثال معمولی برای برنامه Flutter آورده شده است:

name: my_app
description: نمونه برنامه Flutter
version: 1.0.0+1
publish_to: none

environment:
  sdk: ">=3.0.0 <4.0.0"
  flutter: ">=3.10.0"

dependencies:
  flutter:
    sdk: flutter
  http: ^1.1.0
  provider: ^6.0.5
  shared_preferences: ^2.2.0
  path_provider: ^2.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0
  mockito: ^5.4.3

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/fonts/

فیلدهای کلیدی pubspec.yaml: name — نام منحصربه‌فرد بسته (فقط حروف لاتین، زیرخط، اعداد)؛ description — توضیح مختصر (برای انتشار الزامی)؛ version — نسخه معنایی با شماره ساخت اختیاری بعد از علامت مثبت؛ environment — حداقل نسخه‌های Dart SDK و Flutter SDK؛ dependencies — وابستگی‌های اصلی برنامه؛ dev_dependencies — وابستگی‌های فقط برای توسعه و تست؛ flutter — بخش پیکربندی Flutter (assets, fonts, plugins).

فیلد publish_to دسترسی انتشار را کنترل می‌کند: مقدار none انتشار را ممنوع می‌کند (معمول برای برنامه‌ها)، مقدار پیش‌فرض — https://pub.dev. فیلد dependency_overrides امکان بازنویسی اجباری نسخه بسته را در شرایط تعارض فراهم می‌کند — با احتیاط و فقط برای راه‌حل موقت استفاده شود.

وابستگی‌ها و انواع آن‌ها

pub از چهار نوع وابستگی پشتیبانی می‌کند که هر کدام با نحو خاص خود در pubspec.yaml مشخص می‌شوند:

ثبتی (hosted)

نوع استاندارد — بسته از ثبت pub.dev یا ثبت سازگار دیگر بارگیری می‌شود. نام بسته و نسخه مشخص می‌شود. مثال: http: ^1.1.0 آخرین نسخه سازگار را از محدوده >=1.1.0 و <2.0.0 طبق قوانین نسخه‌بندی caret بارگیری می‌کند.

وابستگی‌های SDK

برای اتصال Flutter SDK یا Dart SDK استفاده می‌شود. نحو: flutter: sdk: flutter. بسته از نصب محلی Flutter SDK گرفته می‌شود، نه از ثبت. وابستگی‌های SDK نسخه‌بندی نمی‌شوند — نسخه آن‌ها توسط نسخه فعلی نصب شده Flutter تعیین می‌شود.

مسیری (path)

به دایرکتوری محلی حاوی بسته اشاره می‌کند. برای توسعه کتابخانه و آزمایش بدون انتشار مفید است. نحو:

dependencies:
  my_local_lib:
    path: ../my_local_lib

وابستگی‌های مسیری در pubspec.lock ثابت نمی‌شوند — هر به‌روزرسانی دوباره از مسیر مشخص شده حل می‌شود.

وابستگی‌های Git

امکان اتصال بسته مستقیماً از مخزن git را فراهم می‌کند. شاخه‌ها، برچسب‌ها و کامیت‌ها پشتیبانی می‌شوند:

dependencies:
  my_git_lib:
    git:
      url: https://github.com/user/my_git_lib.git
      ref: main

وابستگی‌های Git برای انشعاب‌ها (fork)، اصلاحات منتشرنشده یا کار روی Pull Request مناسب هستند. توصیه می‌شود به جای شاخه، برچسب یا کامیت خاصی مشخص شود تا از تغییرات غیرمنتظره هنگام ساخت جلوگیری شود.

نسخه‌بندی و محدوده‌ها

pub به شدت از Semantic Versioning 2.0 پیروی می‌کند: قالب MAJOR.MINOR.PATCH، که در آن MAJOR — تغییرات ناسازگار، MINOR — افزوده‌های سازگار با عقب، PATCH — اصلاحات سازگار با عقب است. بر اساس این طرح، pub سازگاری بسته‌ها را تعیین و تعارضات را حل می‌کند.

برای تعیین نسخه‌ها از سه عملگر اصلی در pubspec.yaml استفاده می‌شود:

• Caret (^) — ^1.2.3 معادل >=1.2.3 و <2.0.0 است. رایج‌ترین عملگر، زیرا سازگاری در محدوده نسخه اصلی را فرض می‌کند. برای بسته‌های با نسخه اصلی 0 (صفر) — ^0.1.2 به معنای >=0.1.2 و <0.2.0 است که با قوانین SemVer برای نسخه‌های ناپایدار مطابقت دارد.
• Tilde (~) — ~1.2.3 معادل >=1.2.3 و <1.3.0 است. نسخه فرعی را ثابت می‌کند و فقط به‌روزرسانی‌های patch را مجاز می‌کند. کمتر استفاده می‌شود، عمدتاً زمانی که ناسازگاری در سطح نسخه فرعی مشخص است.
• محدوده دقیق — >=1.2.0 <2.0.0 — نوشتار صریح که کنترل کامل می‌دهد. برای محدودیت‌های پیچیده مفید است، مثلاً هنگام استفاده از چندین نسخه وابستگی‌های گذرا.

پس از اجرای dart pub get، pub فایل pubspec.lock را تولید می‌کند که نسخه‌های دقیق همه بسته‌های حل شده (مستقیم و گذرا) را ثابت می‌کند. این فایل باید در سیستم کنترل نسخه گنجانده شود تا ساخت‌های تکراری در همه ماشین‌ها تضمین شود. هنگام اجرای dart pub upgrade، فایل lock با آخرین نسخه‌های سازگار در محدوده‌های تعیین شده به‌روزرسانی می‌شود.

خطای dependency conflict زمانی رخ می‌دهد که دو بسته محدوده‌های غیرهمپوشانی از یک وابستگی را نیاز دارند. pub گزارش می‌دهد کدام بسته‌ها دچار تعارض شده‌اند و به چه دلیلی. راه‌حل: به‌روزرسانی یکی از بسته‌های متعارض به نسخه سازگار، استفاده از dependency_overrides (اقدام موقت) یا جایگزینی بسته با گزینه دیگر.

دستورات اصلی pub

همه عملیات pub از طریق یک رابط CLI یکپارچه انجام می‌شوند. در Dart SDK از دستور dart pub استفاده می‌شود، در Flutter SDK — معادل flutter pub (علاوه بر این، وابستگی‌های Flutter SDK و پلاگین‌ها را در نظر می‌گیرد). در زیر دستورات کلیدی آورده شده است:

• dart pub get — همه وابستگی‌های مشخص شده در pubspec.yaml را بارگیری می‌کند، نسخه‌ها را حل می‌کند و pubspec.lock را ایجاد/به‌روزرسانی می‌کند. در اولین کلون کردن پروژه یا پس از تغییر وابستگی‌ها اجرا می‌شود.
• dart pub upgrade — همه وابستگی‌ها را به آخرین نسخه‌ها در محدوده pubspec.yaml به‌روزرسانی می‌کند و pubspec.lock را بازنویسی می‌کند. می‌توان یک بسته خاص را به‌روزرسانی کرد: dart pub upgrade http.
• dart pub add <package> — وابستگی جدیدی به pubspec.yaml اضافه می‌کند و بلافاصله pub get را اجرا می‌کند. مثال: dart pub add dio آخرین نسخه بسته dio را اضافه می‌کند.
• dart pub remove <package> — وابستگی را از pubspec.yaml حذف می‌کند و حل گراف را دوباره راه‌اندازی می‌کند.
• dart pub cache repair — همه بسته‌های ذخیره شده را دوباره بارگیری می‌کند. در صورت خرابی حافظه نهان محلی یا خطاهای جمع کنترلی کمک می‌کند.
• dart pub deps — درخت وابستگی را در قالب متنی مناسب نمایش می‌دهد. برای تحلیل وابستگی‌های گذرا و یافتن تکراری‌ها مفید است.
• dart pub publish — بسته جاری را در pub.dev منتشر می‌کند. قبل از انتشار، صحت pubspec.yaml، مجوز و توضیحات را بررسی می‌کند.
• dart pub outdated — فهرست وابستگی‌های قدیمی را با نسخه فعلی، مطلوب و آخرین نسخه موجود نشان می‌دهد. مشابه npm outdated.

همه دستورات به صورت کوتاه شده نیز در دسترس هستند: dart pub get به عنوان dart pub g (همه کوتاه‌سازی‌ها نیستند). در پروژه‌های Flutter، پیشوند flutter به دستورات pub اضافه می‌شود: flutter pub get، flutter pub add و غیره. نسخه Flutter علاوه بر این سازگاری پلاگین‌ها با پلتفرم هدف را بررسی می‌کند.

انتشار در pub.dev

pub.dev — ثبت مرکزی بسته‌های اکوسیستم Dart و Flutter است. تا ژانویه ۲۰۲۵، بیش از ۵۰٬۰۰۰ بسته در آن منتشر شده که مجموعاً بیش از ۱۰ میلیارد بار بارگیری شده‌اند. هر بسته صفحه‌ای با توضیحات، مستندات، ارزیابی‌های محبوبیت (Popularity)، امتیازات Pub Points و نسخه‌ها دارد.

Pub Points — سیستم خودکار ارزیابی کیفیت بسته از ۰ تا ۱۳۰ امتیاز. موارد زیر در نظر گرفته می‌شوند: وجود مجوز، توضیحات، نمونه‌ها، سازگاری با آخرین نسخه پایدار Dart، عدم وجود آسیب‌پذیری، پوشش تست، صحت قالب‌بندی. امتیاز بالا دید بسته را در جستجو و اعتماد کاربران افزایش می‌دهد.

فرآیند انتشار شامل چند مرحله است:

1. pubspec.yaml را بررسی کنید: وجود name, description, version, license (توصیه می‌شود شناسه SPDX مشخص شود، مثلاً MIT).
2. dart pub publish --dry-run را اجرا کنید — شبیه‌سازی انتشار بدون ارسال به سرور، همه فایل‌هایی که در بسته گنجانده می‌شوند و خطاهای احتمالی را نمایش می‌دهد.
3. در اولین انتشار از طریق حساب Google احراز هویت کنید: dart pub publish مرورگر را برای تأیید هویت OAuth باز می‌کند.
4. انتشار را در ترمینال تأیید کنید. پس از ارسال موفق، بسته ظرف چند دقیقه در pub.dev ظاهر می‌شود.

قوانین مهم: فقط بسته‌های با نام منحصربه‌فرد قابل انتشار هستند؛ نسخه منتشر شده را نمی‌توان حذف کرد (فقط می‌توان مخفی کرد — dart pub unpublish — در عرض ۷ روز)؛ برای به‌روزرسانی‌های بزرگ باید قوانین Semantic Versioning رعایت شود، API عمومی بدون تغییر نسخه اصلی شکسته نشود.