pubspec.yaml — co to jest, struktura i konfiguracja zależności w Flutter

Czym jest pubspec.yaml

pubspec.yaml — to manifest w formacie YAML, który menedżer pakietów pub wykorzystuje do zarządzania projektami Dart i Flutter. Znajduje się w katalogu głównym projektu i jest przetwarzany przy każdym poleceniu flutter pub get. W przeciwieństwie do innych platform, gdzie konfiguracja jest rozproszona po wielu plikach, Flutter używa jednego scentralizowanego manifestu do wszystkich potrzeb.

Plik zawiera metadane: nazwę projektu, opis, wersję, autora. Te dane są używane podczas publikowania pakietu na pub.dev oraz podczas budowania aplikacji dla App Store i Google Play. Pole description jest wyświetlane w wynikach wyszukiwania pakietów, dlatego powinno być informacyjne i zawierać słowa kluczowe, po których inni programiści będą mogli znaleźć bibliotekę.

Bez poprawnego pubspec.yaml projekt Flutter nie może zostać zbudowany. Błędy składni lub nieprawidłowe wcięcia prowadzą do natychmiastowego błędu kompilacji z komunikatem Error on line X. YAML jest wrażliwy na spacje: jedna dodatkowa spacja zmienia strukturę danych, a tabulator powoduje błąd składni. Dlatego przy ręcznym edytowaniu pubspec.yaml ważne jest używanie edytora z podświetlaniem składni YAML, na przykład VS Code z oficjalnym rozszerzeniem dla Flutter.

Główne sekcje pubspec.yaml

pubspec.yaml składa się z obowiązkowych i opcjonalnych sekcji. Każda sekcja odpowiada za określony aspekt konfiguracji projektu. Kolejność sekcji nie jest ważna, ale zgodnie z konwencją community przestrzegana jest hierarchia: metadane, środowisko, zależności, zasoby, platformy.

name i description

Pole name określa unikalny identyfikator pakietu w formacie snake_case, składający się tylko z małych liter łacińskich, cyfr i podkreśleń. Pole description — krótki opis projektu do 180 znaków, obowiązkowy do publikacji na pub.dev. Opis powinien wyjaśniać przeznaczenie pakietu, nie powtarzając nazwy, i zawierać słowa kluczowe dla optymalizacji wyszukiwania repozytorium.

name: my_flutter_app
description: Aplikacja do zarządzania zadaniami z Flutter
publish_to: 'none'

version i environment

Pole version używa semantycznego wersjonowania major.minor.patch z opcjonalnym numerem kompilacji po plusie (1.0.0+1). Sekcja environment określa minimalne i maksymalne wersje Dart i Flutter SDK dla zapewnienia zgodności. Jeśli nowa wersja SDK zawiera krytyczne zmiany niezgodne z kodem projektu, kompilacja zostanie przerwana z czytelnym komunikatem o błędzie.

version: 1.0.0+1
environment:
  sdk: '>=3.2.0 <4.0.0'
  flutter: '>=3.16.0'

dependencies i dev_dependencies

Sekcja dependencies wymienia pakiety niezbędne do działania aplikacji w runtime. Sekcja dev_dependencies zawiera pakiety do testowania, generowania kodu i programowania — nie wchodzą one w skład wydania produkcyjnego. Podział zależności jest krytyczny dla wydajności: każdy pakiet w dependencies zwiększa rozmiar końcowego APK lub IPA, a także czas uruchamiania aplikacji z powodu inicjalizacji dodatkowych bibliotek.

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

Konfiguracja assets i czcionek

Sekcja flutter zawiera podsekcje do konfiguracji zasobów, czcionek i parametrów platformy. Zasoby są podłączane przez tablicę paths z określeniem konkretnych plików lub całych katalogów. Wszystkie ścieżki są podawane względem katalogu głównego projektu, a nie względem pubspec.yaml. To ważny niuans, który często powoduje zamieszanie u początkujących programistów 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

Podłączanie assets przez pubspec.yaml udostępnia pliki przez AssetBundle w runtime. Działa to dla obrazów, JSON, plików tekstowych i wszelkich innych zasobów. Flutter automatycznie obsługuje różne rozdzielczości ekranu: jeśli umieścisz images/2x/ i images/3x/, Flutter dobierze odpowiednią wersję obrazu na podstawie device pixel ratio urządzenia. W tym celu wystarczy wskazać w assets tylko katalog główny images/.

Niestandardowe czcionki są dodawane przez sekcję fonts z określeniem family i listą krojów. Po zmianie pubspec.yaml należy wykonać flutter pub get, aby zastosować ustawienia. Czcionki można używać zarówno globalnie w motywie MaterialApp, jak i lokalnie w konkretnych widgetach. Dla każdego kroju można określić weight (100-900) i style (normal, italic), co pozwoli Flutter poprawnie dobierać plik czcionki przy użyciu FontWeight i FontStyle w kodzie.

Zarządzanie zależnościami i wersjami

pub obsługuje kilka sposobów określania źródeł zależności: pub.dev, repozytoria Git, ścieżki lokalne i prywatne repozytoria. Wybór źródła zależy od etapu programowania: dla stabilnych wersji używany jest pub.dev, dla forków i niestandardowych modyfikacji — Git, dla równolegle rozwijanych bibliotek — ścieżka lokalna.

Operator ^version oznacza wersję zgodną: ^1.2.0 dopuszcza wersje >=1.2.0 i <2.0.0. Jest to odpowiednik operatora ~> w CocoaPods i Caret-operatora w npm. pub automatycznie rozwiązuje Dependency Hell przez algorytm SAT-solvera, który znajduje kombinację wersji spełniającą wszystkie ograniczenia. Jeśli taka kombinacja nie istnieje, pub wyświetla szczegółowy komunikat z wskazaniem konfliktujących pakietów.

Plik pubspec.lock ustala dokładne wersje zależności. Powinien być przechowywany w systemie kontroli wersji dla aplikacji, aby zapewnić powtarzalne kompilacje na wszystkich maszynach zespołu. Dla bibliotek pubspec.lock nie jest dołączany do repozytorium, ponieważ użytkownicy biblioteki powinni mieć możliwość używania jej z różnymi wersjami zależności. Polecenie flutter pub upgrade aktualizuje wszystkie zależności zgodnie z ograniczeniami pubspec.yaml, a flutter pub outdated pokazuje, które pakiety można zaktualizować.

Konfiguracja budowania i publikacji

Do publikacji aplikacji na pub.dev ustawienia określane są w sekcji publish_to. Wartość 'none' zabrania przypadkowej publikacji pakietu, co jest ważne dla projektów wewnętrznych lub niepublicznych. Jeśli publish_to jest nieobecne, pub próbuje opublikować pakiet na domyślnym pub.dev, co może prowadzić do niepożądanego wycieku kodu.

Sekcja flutter zawiera parametry platform: generate do automatycznego generowania plików platformowych oraz deferred-components do modułowego ładowania funkcjonalności. Parametr generate: true powoduje, że Flutter automatycznie tworzy i aktualizuje projekty platformowe (iOS, Android, Web) przy dodawaniu nowych platform przez flutter create --platforms. Bez tego parametru struktura folderów platform może się rozsynchronizować z pubspec.yaml.

flutter:
  generate: true
  deferred-components:
    - name: photoEditor
      libraries:
        - package:photo_editor/library.dart

Sekcja platforms określa docelowe platformy dla pakietu. Dla aplikacji jest automatycznie określana przy dodawaniu obsługi konkretnej platformy przez flutter create. Platformy można dodawać i usuwać ręcznie przez edycję pubspec.yaml. Deferred Components pozwalają ładować części aplikacji na żądanie, zmniejszając rozmiar instalacji — jest to szczególnie istotne dla gier i aplikacji z dużą ilością rzadko używanego kontentu.

Przy publikacji pakietu pub sprawdza wszystkie pola pubspec.yaml pod kątem zgodności z wymaganiami repozytorium. Brak obowiązkowych pól name, version i description prowadzi do odrzucenia publikacji. Dodatkowo sprawdzana jest poprawność licencji, obecność README.md i CHANGELOG.md. Pakiety z błędami analizatora kodu (dart analyze) również nie przechodzą walidacji. Po pomyślnej publikacji pakiet staje się dostępny na pub.dev w ciągu kilku minut.

Sekcja dependency_overrides pozwala wymusić wersję pakietu, ignorując ograniczenia z zależności przechodnich. Jest to potężny, ale niebezpieczny mechanizm: przy nieprawidłowym użyciu może prowadzić do niezgodności bibliotek. Używaj dependency_overrides tylko tymczasowo do rozwiązywania konfliktów lub testowania nowych wersji. Po naprawieniu głównych zależności override należy usunąć, aby nie naruszać grafu zależności projektu w długoterminowej perspektywie.

Sekcja executables w pubspec.yaml pozwala wskazywać wykonywalne skrypty, które pub instaluje w PATH przy aktywacji pakietu. Jest to przydatne dla narzędzi CLI napisanych w Dart, na przykład build_runner lub dart_code_metrics. Polecenie dart pub global activate instaluje pakiet globalnie, udostępniając wskazane w executables skrypty z terminala. Dla aplikacji executables zwykle nie są używane, ponieważ punkt wejścia jest określany przez main w lib/main.dart.