pubspec.yaml — vad är det, struktur och konfiguration av beroenden i Flutter

Vad är pubspec.yaml

pubspec.yaml — är en manifestfil i YAML-format som pakethanteraren pub använder för att hantera Dart- och Flutter-projekt. Den finns i projektroten och bearbetas vid varje flutter pub get-kommando. Till skillnad från andra plattformar där konfigurationen är spridd över flera filer, använder Flutter ett centraliserat manifest för alla behov.

Filen innehåller metadata: projektnamn, beskrivning, version, författare. Dessa data används vid publicering av paketet på pub.dev och vid byggning av appen för App Store och Google Play. Fältet description visas i paketets sökresultat, så det bör vara informativt och innehålla nyckelord som andra utvecklare kan använda för att hitta biblioteket.

Utan en korrekt pubspec.yaml kan ett Flutter-projekt inte byggas. Syntaxfel eller felaktiga indrag leder till omedelbart kompileringsfel med meddelandet Error on line X. YAML är känsligt för mellanslag: ett extra mellanslag ändrar datastrukturen och en tabb orsakar ett syntaxfel. Därför är det viktigt att vid manuell redigering av pubspec.yaml använda en editor med YAML-syntaxmarkering, till exempel VS Code med det officiella tillägget för Flutter.

Huvudsektioner i pubspec.yaml

pubspec.yaml består av obligatoriska och valfria sektioner. Varje sektion ansvarar för en specifik aspekt av konfigurationen av projektet. Ordningen på sektionerna är inte viktig, men enligt community-konventionen följs en hierarki: metadata, miljö, beroenden, resurser, plattformar.

name och description

Fältet name anger paketets unika identifierare i snake_case-format, bestående av endast små latinska bokstäver, siffror och understreck. Fältet description — en kort beskrivning av projektet upp till 180 tecken, obligatorisk för publicering på pub.dev. Beskrivningen ska förklara paketets syfte, utan att upprepa namnet, och innehålla nyckelord för sökoptimering av databasen.

name: my_flutter_app
description: App för uppgiftshantering med Flutter
publish_to: 'none'

version och environment

Fältet version använder semantisk versionshantering major.minor.patch med ett valfritt byggnummer efter plustecknet (1.0.0+1). Sektionen environment anger de lägsta och högsta versionerna av Dart och Flutter SDK för att garantera kompatibilitet. Om en ny version av SDK innehåller kritiska ändringar som är inkompatibla med projektkoden, avbryts kompileringen med ett tydligt felmeddelande.

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

dependencies och dev_dependencies

Sektionen dependencies listar de paket som krävs för att applikationen ska fungera under körning. Sektionen dev_dependencies innehåller paket för testning, kodgenerering och utveckling — de ingår inte i release-bygget. Uppdelningen av beroenden är avgörande för prestanda: varje paket i dependencies ökar storleken på den slutliga APK- eller IPA-filen samt appens starttid på grund av initialisering av ytterligare 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

Konfiguration av assets och typsnitt

Sektionen flutter innehåller undersektioner för konfiguration av resurser, typsnitt och plattformsparametrar. Resurser kopplas via en array paths med angivelse av specifika filer eller hela kataloger. Alla sökvägar anges relativt projektroten, inte relativt pubspec.yaml. Detta är en viktig nyans som ofta orsakar förvirring hos nybörjare inom 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

Genom att koppla assets via pubspec.yaml görs filerna tillgängliga via AssetBundle under körning. Detta fungerar för bilder, JSON, textfiler och alla andra resurser. Flutter stöder automatiskt olika skärmupplösningar: om du placerar images/2x/ och images/3x/ väljer Flutter rätt version av bilden baserat på enhetens device pixel ratio. För detta räcker det att i assets endast ange rotmappen images/.

Anpassade typsnitt läggs till via sektionen fonts med angivelse av family och lista över typsnitt. Efter ändring av pubspec.yaml måste flutter pub get köras för att tillämpa inställningarna. Typsnitt kan användas både globalt i MaterialApp-temat och lokalt i specifika widgetar. För varje typsnitt kan weight (100-900) och style (normal, italic) anges, vilket gör att Flutter kan välja rätt typsnittsfil vid användning av FontWeight och FontStyle i koden.

Hantering av beroenden och versioner

pub stöder flera sätt att ange källor för beroenden: pub.dev, Git-databaser, lokala sökvägar och privata databaser. Valet av källa beror på utvecklingsstadiet: för stabila versioner används pub.dev, för forks och anpassade ändringar — Git, för parallellt utvecklade bibliotek — lokal sökväg.

Operatorn ^version betyder en kompatibel version: ^1.2.0 tillåter versioner >=1.2.0 och <2.0.0. Detta är analogt med operatorn ~> i CocoaPods och Caret-operatorn i npm. pub löser automatiskt Dependency Hell genom en SAT-lösningsalgoritm som hittar en kombination av versioner som uppfyller alla begränsningar. Om en sådan kombination inte finns, visar pub ett detaljerat meddelande med angivelse av de konflikterande paketen.

Filenen pubspec.lock fastställer de exakta versionerna av beroenden. Den bör lagras i versionskontrollsystemet för applikationer för att säkerställa reproducerbara byggen på alla teamets maskiner. För bibliotek inkluderas pubspec.lock inte i databasen, eftersom biblioteksanvändare bör kunna använda det med olika versioner av beroenden. Kommandot flutter pub upgrade uppdaterar alla beroenden enligt begränsningarna i pubspec.yaml, och flutter pub outdated visar vilka paket som kan uppdateras.

Konfiguration av bygge och publicering

För publicering av appen på pub.dev anges inställningarna i sektionen publish_to. Värdet 'none' förhindrar oavsiktlig publicering av paketet, vilket är viktigt för interna eller icke-offentliga projekt. Om publish_to saknas, försöker pub publicera paketet på standard pub.dev, vilket kan leda till oönskad läckage av kod.

Sektionen flutter innehåller plattformsparametrar: generate för automatisk generering av plattfilsfiler och deferred-components för modulär laddning av funktionalitet. Parametern generate: true gör att Flutter automatiskt skapar och uppdaterar plattformsprojekt (iOS, Android, Web) vid tillägg av nya plattformar via flutter create --platforms. Utan denna parameter kan strukturen på plattformsmapparna desynkroniseras med pubspec.yaml.

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

Sektionen platforms anger målplattformarna för paketet. För applikationer bestäms den automatiskt vid tillägg av stöd för en specifik plattform via flutter create. Plattformar kan läggas till och tas bort manuellt genom redigering av pubspec.yaml. Deferred Components gör det möjligt att ladda delar av appen på begäran, vilket minskar installationsstorleken — detta är särskilt relevant för spel och applikationer med mycket sällan använt innehåll.

Vid publicering av ett paket kontrollerar pub alla fält i pubspec.yaml för överensstämmelse med kraven i databasen. Avsaknad av obligatoriska fält name, version och description leder till avslag av publiceringen. Dessutom kontrolleras licensens giltighet, förekomsten av README.md och CHANGELOG.md. Paket med fel i kodanalysatorn (dart analyze) klarar inte heller valideringen. Efter framgångsrik publicering blir paketet tillgängligt på pub.dev inom några minuter.

Sektionen dependency_overrides gör det möjligt att tvinga en paketversion, ignorera begränsningar från transitiva beroenden. Detta är en kraftfull men farlig mekanism: vid felaktig användning kan den leda till inkompatibilitet av bibliotek. Använd dependency_overrides endast tillfälligt för att lösa konflikter eller testa nya versioner. Efter att ha åtgärdat de viktigaste beroendena bör override tas bort för att inte störa projektets beroendegraf på lång sikt.

Sektionen executables i pubspec.yaml gör det möjligt att ange körbara skript som pub installerar i PATH vid aktivering av paketet. Detta är användbart för CLI-verktyg skrivna i Dart, till exempel build_runner eller dart_code_metrics. Kommandot dart pub global activate installerar paketet globalt och gör skripten som anges i executables tillgängliga från terminalen. För applikationer används executables vanligtvis inte, eftersom startpunkten bestäms via main i lib/main.dart.