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 задає мінімальні та максимальні версії 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 підбере потрібну версію зображення на основі коефіцієнта пікселів пристрою. Для цього достатньо вказати в 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, для форків та кастомних модифікацій — Git, для бібліотек, що розробляються паралельно, — локальний шлях.

Оператор ^version означає сумісну версію: ^1.2.0 дозволяє версії >=1.2.0 та <2.0.0. Це аналог оператора ~> у CocoaPods та Caret-оператора в npm. pub автоматично вирішує Dependency Hell через алгоритм SAT-солвера, який знаходить комбінацію версій, що задовольняє всі обмеження. Якщо такої комбінації не існує, 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.