Что такое pubspec.yaml и как управлять зависимостями во Flutter?

pubspec.yaml во Flutter

pubspec.yaml — манифест Flutter/Dart-проекта. Описывает метаданные пакета, зависимости, ресурсы и настройки Flutter. Это аналог package.json в Node.js или pyproject.toml в Python.

Структура файла

name: my_app
description: Мобильное приложение для задач.
publish_to: none  # не публиковать на pub.dev

version: 1.2.3+5  # semver + build number (используется в магазинах)

environment:
  sdk: '>=3.0.0 <4.0.0'  # ограничение версии Dart SDK

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0          # любая совместимая версия >= 1.2.0 < 2.0.0
  go_router: ^14.0.0
  shared_preferences: ^2.3.0
  intl: ^0.19.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^4.0.0
  mockito: ^5.4.0
  build_runner: ^2.4.0

flutter:
  uses-material-design: true

  assets:
    - assets/images/
    - assets/icons/logo.png
    - assets/translations/en.json

  fonts:
    - family: Rubik
      fonts:
        - asset: assets/fonts/Rubik-Regular.ttf
        - asset: assets/fonts/Rubik-Bold.ttf
          weight: 700

Версионирование зависимостей

Dart использует семантическое версионирование с несколькими форматами ограничений:

• ^1.2.0 — caret: от 1.2.0 до <2.0.0 (рекомендуется)
• '>=1.2.0 <2.0.0' — явный диапазон
• 1.2.0 — точная версия (жёсткая блокировка)
• any — любая версия (не рекомендуется в production)

Добавление пакета

# Через CLI (рекомендуется)
flutter pub add http
flutter pub add --dev mockito build_runner

# Обновление до последних совместимых версий
flutter pub upgrade

# Обновление с нарушением ограничений (мажорная версия)
flutter pub upgrade --major-versions

# Получение зависимостей после ручного редактирования pubspec.yaml
flutter pub get

Локальные и git-зависимости

dependencies:
  # Локальный пакет (монорепо или разработка)
  my_utils:
    path: ../my_utils

  # Git-репозиторий
  some_package:
    git:
      url: https://github.com/example/some_package.git
      ref: main  # ветка, тег или SHA

  # Конкретная папка в git-репозитории
  another_package:
    git:
      url: https://github.com/example/mono.git
      path: packages/another_package

pubspec.lock

После flutter pub get создаётся pubspec.lock — фиксирует точные версии всех транзитивных зависимостей. Для приложений файл нужно коммитить в git. Для библиотек — добавлять в .gitignore.

Подводные камни

• YAML чувствителен к отступам — используйте 2 пробела, никогда табы; один неверный отступ ломает весь файл.
• Версия приложения в формате 1.2.3+5: число после + — это versionCode на Android и CFBundleVersion на iOS; его нужно увеличивать при каждой публикации.
• Конфликт версий (version solving failed) возникает, когда два пакета требуют несовместимые версии одной зависимости — решайте через dependency_overrides (временный workaround, не рекомендуется в production).
• Пути в разделе assets чувствительны к регистру на Linux/Mac и нечувствительны на Windows — тестируйте на целевой ОС.
• Добавление пути к директории (assets/images/) включает только файлы первого уровня, не рекурсивно.
• После изменения pubspec.yaml вручную всегда запускайте flutter pub get — IDE не всегда делает это автоматически.
• dev_dependencies не входят в production-сборку, но если ошибочно поместить инструмент сборки (например, build_runner) в dependencies — он попадёт в финальный бинарник.

• Сводить «pubspec.yaml и как управлять зависимостями во Flutter» к синтаксису и не объяснять platform channel.
• Игнорировать жизненный цикл, основной поток или момент освобождения ресурсов в сценарии flutter-19.
• Выбирать API по привычке, не проверяя состояние, ошибки, доступность и платформенные ограничения.

• Формулирует точную модель для «pubspec.yaml и как управлять зависимостями во Flutter» и подтверждает ее корректным примером.
• Умеет связать ответ с widget tree, тестированием и отладкой на устройстве.
• Называет ограничения подхода flutter-19, включая производительность, память и сопровождение.