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 не може да бъде изграден. Синтактични грешки или неправилни отстъпи водят до незабавен провал на компилацията със съобщение Error on line 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 задава минималните и максималните версии на 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, така и локално в конкретни widget-и. За всеки шрифт може да се посочи 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 само временно за разрешаване на конфликти или тестване на нови версии. След коригиране на основните зависимости override трябва да се премахне, за да не нарушава графа на зависимостите на проекта в дългосрочен план.

Секцията executables в pubspec.yaml позволява посочване на изпълними скриптове, които pub инсталира в PATH при активиране на пакета. Това е полезно за CLI инструменти, написани на Dart, например build_runner или dart_code_metrics. Командата dart pub global activate инсталира пакета глобално, правейки скриптовете, посочени в executables, достъпни от терминала. За приложения executables обикновено не се използват, тъй като входната точка се определя чрез main в lib/main.dart.