pub: ключевые понятия, менеджер пакетов Dart и pubspec.yaml

Что такое pub?

pub (Package Universal Browser) — встроенный менеджер пакетов, который поставляется вместе с Dart SDK. Он управляет внешними библиотеками, разрешает конфликты версий, загружает транзитивные зависимости и кэширует пакеты локально. В экосистеме Flutter pub используется как основной инструмент для подключения плагинов навигации, HTTP-клиентов, state-менеджеров и других компонентов.

Основные функции pub включают: установку зависимостей из реестра pub.dev, локальных путей (path-зависимости) и 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 — семантическая версия с опциональным build-номером после плюса; 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-зависимости удобны для форков, неопубликованных исправлений или работы над 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 для нестабильных версий.
• Тильда (~) — ~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-проектах перед командами pub добавляется префикс flutter: flutter pub get, flutter pub add и так далее. Flutter-версия дополнительно проверяет совместимость плагинов с целевой платформой.

Публикация на pub.dev

pub.dev — центральный реестр пакетов экосистемы Dart и Flutter. На январь 2025 года там опубликовано более 50 000 пакетов, суммарно загруженных свыше 10 миллиардов раз. Каждый пакет имеет страницу с описанием, документацией, оценками популярности (Popularity), баллами Pub Points и версиями.

Pub Points — автоматическая система оценки качества пакета от 0 до 130 баллов. Учитываются: наличие лицензии, описание, примеры, совместимость с последней стабильной версией 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 — в течение 7 дней); для крупных обновлений следует следовать правилам Semantic Versioning, не ломать публичный API без смены мажорной версии.