pub: Schlüsselkonzepte, Dart-Paketmanager und pubspec.yaml

Was ist pub?

pub (Package Universal Browser) — ein integrierter Paketmanager, der mit dem Dart SDK ausgeliefert wird. Er verwaltet externe Bibliotheken, löst Versionskonflikte, lädt transitive Abhängigkeiten herunter und speichert Pakete lokal zwischen. Im Flutter-Ökosystem wird pub als Hauptwerkzeug zum Anbinden von Navigations-Plugins, HTTP-Clients, State-Managern und anderen Komponenten verwendet.

Zu den Hauptfunktionen von pub gehören: Installieren von Abhängigkeiten aus der pub.dev-Registrierung, lokalen Pfaden (Pfadabhängigkeiten) und Git-Repositories; Versionsauflösung nach den Regeln der semantischen Versionierung; Zwischenspeichern heruntergeladener Pakete in einem Systemverzeichnis; Veröffentlichen eigener Pakete in der öffentlichen Registrierung. Alle diese Operationen sind über den CLI-Befehl dart pub oder das Äquivalent flutter pub verfügbar.

Die Architektur von pub basiert auf einem geschlossenen Abhängigkeitsgraphen: Der Manager erstellt einen Baum, in dem jedes Paket genau einmal vorkommt. Wenn zwei Bibliotheken unterschiedliche Versionen desselben Pakets benötigen, versucht pub einen kompatiblen Bereich zu finden oder meldet einen Konfliktfehler. Dies unterscheidet sich vom Ansatz von npm, der mehrere Versionen desselben Pakets in verschiedenen Baumknoten zulässt.

Struktur von pubspec.yaml

Die Datei pubspec.yaml — die zentrale Konfigurationsdatei eines jeden Dart- oder Flutter-Projekts. Sie ist im YAML-Format geschrieben und enthält Metadaten, Abhängigkeiten, Build-Konfiguration und SDK-Einschränkungen. Nachfolgend ein typisches Beispiel für eine Flutter-Anwendung:

name: my_app
description: Beispiel einer Flutter-App
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/

Schlüsselfelder von pubspec.yaml: name — eindeutiger Paketname (nur lateinische Buchstaben, Unterstrich, Ziffern); description — Kurzbeschreibung (erforderlich für die Veröffentlichung); version — semantische Version mit optionaler Build-Nummer nach dem Pluszeichen; environment — minimale Dart SDK- und Flutter SDK-Versionen; dependencies — Hauptabhängigkeiten der Anwendung; dev_dependencies — Abhängigkeiten nur für Entwicklung und Tests; flutter — Flutter-Konfigurationsabschnitt (Assets, Schriftarten, Plugins).

Das Feld publish_to steuert die Verfügbarkeit der Veröffentlichung: Der Wert none verbietet die Veröffentlichung (typisch für Anwendungen), der Standardwert ist https://pub.dev. Das Feld dependency_overrides ermöglicht das erzwungene Überschreiben einer Paketversion in Konfliktsituationen — mit Vorsicht verwenden, nur als temporäre Lösung.

Abhängigkeiten und ihre Arten

pub unterstützt vier Arten von Abhängigkeiten, die jeweils mit eigener Syntax innerhalb von pubspec.yaml angegeben werden:

Gehostet (hosted)

Der Standardtyp — das Paket wird aus der pub.dev-Registrierung oder einer anderen kompatiblen Registrierung heruntergeladen. Paketname und Version werden angegeben. Beispiel: http: ^1.1.0 lädt die neueste kompatible Version aus dem Bereich >=1.1.0 und <2.0.0 gemäß den Caret-Versionierungsregeln herunter.

SDK-Abhängigkeiten

Werden verwendet, um das Flutter SDK oder Dart SDK einzubinden. Syntax: flutter: sdk: flutter. Das Paket wird aus der lokalen Flutter SDK-Installation bezogen, nicht aus der Registrierung. SDK-Abhängigkeiten werden nicht versioniert — ihre Version wird durch die aktuell installierte Flutter-Version bestimmt.

Pfad (path)

Zeigen auf ein lokales Verzeichnis, das ein Paket enthält. Nützlich beim Entwickeln einer Bibliothek und Testen ohne Veröffentlichung. Syntax:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Pfadabhängigkeiten werden nicht in pubspec.lock fixiert — jede Aktualisierung wird vom angegebenen Pfad aus neu aufgelöst.

Git

Ermöglichen das Einbinden eines Pakets direkt aus einem Git-Repository. Branches, Tags und Commits werden unterstützt:

dependencies:
  my_git_lib:
    git:
      url: https://github.com/user/my_git_lib.git
      ref: main

Git-Abhängigkeiten sind praktisch für Forks, unveröffentlichte Korrekturen oder die Arbeit an Pull Requests. Es wird empfohlen, anstelle eines Branches einen bestimmten Tag oder Commit anzugeben, um unerwartete Änderungen während des Builds zu vermeiden.

Versionierung und Bereiche

pub folgt streng Semantic Versioning 2.0: Format MAJOR.MINOR.PATCH, wobei MAJOR — inkompatible Änderungen, MINOR — abwärtskompatible Erweiterungen, PATCH — abwärtskompatible Korrekturen. Basierend auf diesem Schema bestimmt pub die Paketkompatibilität und löst Konflikte.

Drei Hauptoperatoren werden zur Angabe von Versionen in pubspec.yaml verwendet:

• Caret (^) — ^1.2.3 entspricht >=1.2.3 und <2.0.0. Der häufigste Operator, da er Kompatibilität innerhalb der Hauptversion bedeutet. Für Pakete mit Hauptversion 0 (null) — ^0.1.2 bedeutet >=0.1.2 und <0.2.0, was den SemVer-Regeln für instabile Versionen folgt.
• Tilde (~) — ~1.2.3 entspricht >=1.2.3 und <1.3.0. Fixiert die Nebenversion und erlaubt nur Patch-Updates. Wird seltener verwendet, hauptsächlich wenn eine Inkompatibilität auf Nebenversionsebene bekannt ist.
• Exakter Bereich — >=1.2.0 <2.0.0 — explizite Notation, die vollständige Kontrolle bietet. Nützlich für komplexe Einschränkungen, z. B. bei Verwendung mehrerer Versionen transitiver Abhängigkeiten.

Nach der Ausführung von dart pub get generiert pub eine pubspec.lock-Datei, die die exakten Versionen aller aufgelösten Pakete (direkt und transitiv) fixiert. Diese Datei muss in die Versionskontrolle aufgenommen werden, um reproduzierbare Builds auf allen Maschinen zu gewährleisten. Bei der Ausführung von dart pub upgrade wird die Lock-Datei auf die neuesten kompatiblen Versionen innerhalb der angegebenen Einschränkungen aktualisiert.

Ein Abhängigkeitskonflikt-Fehler tritt auf, wenn zwei Pakete sich nicht überschneidende Bereiche derselben Abhängigkeit erfordern. pub meldet, welche Pakete im Konflikt stehen und warum. Lösung: Aktualisieren Sie eines der konfligierenden Pakete auf eine kompatible Version, verwenden Sie dependency_overrides (temporäre Maßnahme) oder wechseln Sie zu einem alternativen Paket.

Wichtige pub-Befehle

Alle pub-Operationen werden über eine einheitliche CLI-Schnittstelle ausgeführt. Das Dart SDK verwendet den Befehl dart pub, das Flutter SDK das Äquivalent flutter pub (berücksichtigt zusätzlich Flutter SDK-Abhängigkeiten und Plugins). Nachfolgend die wichtigsten Befehle:

• dart pub get — lädt alle in pubspec.yaml angegebenen Abhängigkeiten herunter, löst Versionen auf und erstellt/aktualisiert pubspec.lock. Ausführen beim ersten Klonen eines Projekts oder nach Änderung von Abhängigkeiten.
• dart pub upgrade — aktualisiert alle Abhängigkeiten auf die neuesten Versionen innerhalb der pubspec.yaml-Einschränkungen und überschreibt pubspec.lock. Ein einzelnes Paket kann aktualisiert werden: dart pub upgrade http.
• dart pub add <package> — fügt eine neue Abhängigkeit zu pubspec.yaml hinzu und führt sofort pub get aus. Beispiel: dart pub add dio fügt die neueste Version des Pakets dio hinzu.
• dart pub remove <package> — entfernt eine Abhängigkeit aus pubspec.yaml und startet die Graphauflösung neu.
• dart pub cache repair — lädt alle zwischengespeicherten Pakete neu. Hilft bei beschädigtem lokalen Cache oder Prüfsummenfehlern.
• dart pub deps — zeigt den Abhängigkeitsbaum in einem praktischen Textformat an. Nützlich zur Analyse transitiver Abhängigkeiten und zum Auffinden von Duplikaten.
• dart pub publish — veröffentlicht das aktuelle Paket auf pub.dev. Vor der Veröffentlichung werden pubspec.yaml, Lizenz und Beschreibung validiert.
• dart pub outdated — zeigt eine Liste veralteter Abhängigkeiten mit aktueller, gewünschter und neuester verfügbarer Version an. Analog zu npm outdated.

Alle Befehle sind auch in Kurzform dart pub get als dart pub g verfügbar (nicht alle Abkürzungen). In Flutter-Projekten wird den Befehlen flutter vorangestellt: flutter pub get, flutter pub add usw. Die Flutter-Version prüft zusätzlich die Plugin-Kompatibilität mit der Zielplattform.

Veröffentlichung auf pub.dev

pub.dev — die zentrale Paketregistrierung des Dart- und Flutter-Ökosystems. Stand Januar 2025 sind dort über 50.000 Pakete veröffentlicht, mit insgesamt über 10 Milliarden Downloads. Jedes Paket hat eine Seite mit Beschreibung, Dokumentation, Beliebtheitsbewertungen, Pub Points und Versionen.

Pub Points — ein automatisiertes Paketqualitäts-Bewertungssystem von 0 bis 130 Punkten. Es berücksichtigt: Vorhandensein einer Lizenz, Beschreibung, Beispiele, Kompatibilität mit der neuesten stabilen Dart-Version, Fehlen von Schwachstellen, Testabdeckung, korrekte Formatierung. Eine hohe Punktzahl erhöht die Sichtbarkeit des Pakets in der Suche und das Vertrauen der Benutzer.

Der Veröffentlichungsprozess umfasst mehrere Schritte:

1. pubspec.yaml überprüfen: sicherstellen, dass name, description, version, license vorhanden sind (SPDX-Kennung empfohlen, z. B. MIT).
2. dart pub publish --dry-run ausführen — eine Simulation ohne Senden an den Server, zeigt alle Dateien, die in das Paket aufgenommen werden, und mögliche Fehler an.
3. Bei der ersten Veröffentlichung über ein Google-Konto authentifizieren: dart pub publish öffnet einen Browser für die OAuth-Authentifizierung.
4. Veröffentlichung im Terminal bestätigen. Nach erfolgreichem Upload erscheint das Paket innerhalb weniger Minuten auf pub.dev.

Wichtige Regeln: Es können nur Pakete mit eindeutigem Namen veröffentlicht werden; eine einmal veröffentlichte Version kann nicht gelöscht werden (nur ausgeblendet — dart pub unpublish — innerhalb von 7 Tagen); bei größeren Aktualisierungen die Semantic Versioning-Regeln befolgen, die öffentliche API nicht ohne Änderung der Hauptversion brechen.