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 состоит из обязательных и опциональных секций. Каждая секция отвечает за определённый аспект конфигурации проекта. Порядок секций не важен, но по соглашению community соблюдается иерархия: метаданные, окружение, зависимости, ресурсы, платформы.

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 перечисляет пакеты, необходимые для работы приложения в runtime. Секция 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 в runtime. Это работает для изображений, 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, для форков и кастомных модификаций — 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 пытается опубликовать пакет на default 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.