pubspec.yaml — was ist das, Struktur und Abhängigkeitskonfiguration in Flutter

Was ist pubspec.yaml

pubspec.yaml ist eine Manifestdatei im YAML-Format, die der Paketmanager pub zur Verwaltung von Dart- und Flutter-Projekten verwendet. Sie befindet sich im Projektstammverzeichnis und wird bei jedem flutter pub get-Befehl verarbeitet. Im Gegensatz zu anderen Plattformen, bei denen die Konfiguration auf mehrere Dateien verteilt ist, verwendet Flutter ein einziges zentralisiertes Manifest für alle Anforderungen.

Die Datei enthält Metadaten: Projektname, Beschreibung, Version, Autor. Diese Daten werden bei der Veröffentlichung eines Pakets auf pub.dev und beim Erstellen der Anwendung für App Store und Google Play verwendet. Das Feld description wird in den Paketsuchergebnissen angezeigt, daher sollte es informativ sein und Schlüsselwörter enthalten, mit denen andere Entwickler die Bibliothek finden können.

Ohne eine korrekte pubspec.yaml kann ein Flutter-Projekt nicht erstellt werden. Syntaxfehler oder falsche Einrückung führen zu einem sofortigen Kompilierungsfehler mit einer Meldung Error on line X. YAML reagiert empfindlich auf Leerzeichen: Ein zusätzliches Leerzeichen ändert die Datenstruktur, und Tabulatoren verursachen einen Syntaxfehler. Daher ist es beim manuellen Bearbeiten von pubspec.yaml wichtig, einen Editor mit YAML-Syntaxhervorhebung zu verwenden, z. B. VS Code mit der offiziellen Flutter-Erweiterung.

Hauptabschnitte von pubspec.yaml

pubspec.yaml besteht aus erforderlichen und optionalen Abschnitten. Jeder Abschnitt ist für einen bestimmten Aspekt der Konfiguration des Projekts verantwortlich. Die Reihenfolge der Abschnitte spielt keine Rolle, aber nach der Konvention der Community wird die Hierarchie eingehalten: Metadaten, Umgebung, Abhängigkeiten, Ressourcen, Plattformen.

name und description

Das Feld name legt eine eindeutige Paketkennung im snake_case-Format fest, die nur aus Kleinbuchstaben, Ziffern und Unterstrichen besteht. Das Feld description ist eine kurze Projektzusammenfassung von bis zu 180 Zeichen, die für die Veröffentlichung auf pub.dev erforderlich ist. Die Beschreibung sollte den Zweck des Pakets erklären, ohne den Namen zu wiederholen, und Schlüsselwörter zur Suchoptimierung des Repositorys enthalten.

name: my_flutter_app
description: Aufgabenverwaltungs-App mit Flutter
publish_to: 'none'

version und environment

Das Feld version verwendet semantische Versionierung major.minor.patch mit einer optionalen Build-Nummer nach dem Pluszeichen (1.0.0+1). Der Abschnitt environment legt die minimalen und maximalen Versionen des Dart- und Flutter-SDK fest, um Kompatibilität zu gewährleisten. Wenn eine neue SDK-Version inkompatible Änderungen enthält, die nicht mit dem Projektcode kompatibel sind, wird der Build mit einer klaren Fehlermeldung abgebrochen.

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

dependencies und dev_dependencies

Der Abschnitt dependencies listet Pakete auf, die für die Ausführung der Anwendung zur Laufzeit erforderlich sind. Der Abschnitt dev_dependencies enthält Pakete für Tests, Codegenerierung und Entwicklung — sie werden nicht in den Release-Build aufgenommen. Die Trennung der Abhängigkeiten ist für die Leistung entscheidend: Jedes Paket in dependencies erhöht die Größe der endgültigen APK oder IPA sowie die Startzeit der Anwendung aufgrund der Initialisierung zusätzlicher Bibliotheken.

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

Konfiguration von Assets und Schriftarten

Der Abschnitt flutter enthält Unterabschnitte zur Konfiguration von Ressourcen, Schriftarten und Plattformparametern. Ressourcen werden über ein paths-Array eingebunden, das bestimmte Dateien oder ganze Verzeichnisse angibt. Alle Pfade werden relativ zum Projektstamm angegeben, nicht relativ zur pubspec.yaml. Dies ist eine wichtige Nuance, die bei Anfängern der Flutter-Entwicklung oft für Verwirrung sorgt.

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

Das Einbinden von Assets über pubspec.yaml macht Dateien zur Laufzeit über AssetBundle zugänglich. Dies funktioniert für Bilder, JSON, Textdateien und beliebige andere Ressourcen. Flutter unterstützt automatisch verschiedene Bildschirmauflösungen: Wenn Sie images/2x/ und images/3x/ hinzufügen, wählt Flutter die entsprechende Bildversion basierend auf dem Geräte-Pixel-Verhältnis aus. Dazu genügt es, in assets nur den Stammordner images/ anzugeben.

Benutzerdefinierte Schriftarten werden über den Abschnitt fonts mit einem Familiennamen und einer Liste von Stilen hinzugefügt. Nach der Änderung der pubspec.yaml muss flutter pub get ausgeführt werden, um die Änderungen zu übernehmen. Schriftarten können sowohl global im MaterialApp-Theme als auch lokal in bestimmten Widgets verwendet werden. Für jeden Stil können Sie weight (100–900) und style (normal, italic) angeben, sodass Flutter bei Verwendung von FontWeight und FontStyle im Code die richtige Schriftartdatei auswählen kann.

Abhängigkeits- und Versionsverwaltung

pub unterstützt mehrere Möglichkeiten zur Angabe von Quellen für Abhängigkeiten: pub.dev, Git-Repositorys, lokale Pfade und private Repositorys. Die Wahl der Quelle hängt von der Entwicklungsphase ab: Für stabile Versionen wird pub.dev verwendet, für Forks und benutzerdefinierte Änderungen Git, für parallel entwickelte Bibliotheken der lokale Pfad.

Der Operator ^version bedeutet eine kompatible Version: ^1.2.0 erlaubt Versionen >=1.2.0 und <2.0.0. Dies ist analog zum Operator ~> in CocoaPods und zum Caret-Operator in npm. pub löst das Dependency-Problem automatisch durch einen SAT-Solver-Algorithmus, der eine Kombination von Versionen findet, die alle Einschränkungen erfüllt. Wenn eine solche Kombination nicht existiert, gibt pub eine detaillierte Meldung aus, die die konfliktierenden Pakete angibt.

Die Datei pubspec.lock fixiert die genauen Versionen der Abhängigkeiten. Sie sollte für Anwendungen im Versionskontrollsystem gespeichert werden, um reproduzierbare Builds auf allen Maschinen des Teams zu gewährleisten. Für Bibliotheken wird pubspec.lock nicht in das Repository aufgenommen, da die Benutzer der Bibliothek in der Lage sein sollten, sie mit verschiedenen Abhängigkeitsversionen zu verwenden. Der Befehl flutter pub upgrade aktualisiert alle Abhängigkeiten gemäß den Einschränkungen der pubspec.yaml, während flutter pub outdated anzeigt, welche Pakete aktualisiert werden können.

Build- und Veröffentlichungskonfiguration

Um eine Anwendung auf pub.dev zu veröffentlichen, werden die Einstellungen im Abschnitt publish_to angegeben. Der Wert 'none' verhindert die versehentliche Veröffentlichung des Pakets, was für interne oder nicht öffentliche Projekte wichtig ist. Wenn publish_to fehlt, versucht pub, das Paket auf dem Standard-pub.dev zu veröffentlichen, was zu einem unerwünschten Code-Leck führen kann.

Der Abschnitt flutter enthält Plattformparameter: generate für die automatische Generierung von Plattformdateien und deferred-components für das modulare Laden von Funktionen. Der Parameter generate: true zwingt Flutter, beim Hinzufügen neuer Plattformen über flutter create --platforms automatisch Plattformprojekte (iOS, Android, Web) zu erstellen und zu aktualisieren. Ohne diesen Parameter kann die Plattformordnerstruktur mit der pubspec.yaml nicht mehr synchron sein.

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

Der Abschnitt platforms legt die Zielplattformen für das Paket fest. Für Anwendungen wird er automatisch beim Hinzufügen der Unterstützung für eine bestimmte Plattform über flutter create bestimmt. Plattformen können durch Bearbeiten der pubspec.yaml manuell hinzugefügt und entfernt werden. Deferred Components ermöglichen das bedarfsgesteuerte Laden von Teilen der Anwendung und reduzieren so die Installationsgröße — dies ist besonders relevant für Spiele und Anwendungen mit einer großen Menge selten genutzter Inhalte.

Beim Veröffentlichen eines Pakets überprüft pub alle Felder der pubspec.yaml auf Übereinstimmung mit den Anforderungen des Repositorys. Das Fehlen der Pflichtfelder name, version und description führt zur Ablehnung der Veröffentlichung. Zusätzlich werden die Korrektheit der Lizenz und das Vorhandensein von README.md und CHANGELOG.md überprüft. Pakete mit Fehlern des Code-Analyzers (dart analyze) bestehen die Validierung ebenfalls nicht. Nach erfolgreicher Veröffentlichung ist das Paket innerhalb weniger Minuten auf pub.dev verfügbar.

Der Abschnitt dependency_overrides ermöglicht es, eine bestimmte Paketversion zu erzwingen und dabei die Einschränkungen aus transitiven Abhängigkeiten zu ignorieren. Dies ist ein mächtiger, aber gefährlicher Mechanismus: Bei falscher Verwendung kann er zu Inkompatibilitäten zwischen Bibliotheken führen. Verwenden Sie dependency_overrides nur vorübergehend zur Lösung von Konflikten oder zum Testen neuer Versionen. Nachdem die Hauptabhängigkeiten korrigiert wurden, sollte die Überschreibung entfernt werden, um den Abhängigkeitsgraphen des Projekts langfristig nicht zu beschädigen.

Der Abschnitt executables in pubspec.yaml ermöglicht die Angabe ausführbarer Skripte, die pub bei der Aktivierung eines Pakets im PATH installiert. Dies ist nützlich für CLI-Tools, die in Dart geschrieben sind, wie build_runner oder dart_code_metrics. Der Befehl dart pub global activate installiert das Paket global und macht die in executables angegebenen Skripte vom Terminal aus zugänglich. Für Anwendungen werden executables in der Regel nicht verwendet, da der Einstiegspunkt über main in lib/main.dart definiert wird.