pubspec.yaml — ano ito, istraktura at pagsasaayos ng mga dependency sa Flutter

Ano ang pubspec.yaml

pubspec.yaml — ay isang manifest file sa YAML format na ginagamit ng package manager na pub para sa pamamahala ng mga proyekto ng Dart at Flutter. Ito ay matatagpuan sa root ng proyekto at pinoproseso sa bawat flutter pub get command. Hindi tulad ng ibang platform kung saan ang configuration ay nakakalat sa maraming file, ang Flutter ay gumagamit ng isang sentralisadong manifest para sa lahat ng pangangailangan.

Ang file ay naglalaman ng metadata: pangalan ng proyekto, paglalarawan, bersyon, may-akda. Ang data na ito ay ginagamit kapag naglalathala ng package sa pub.dev at kapag nagbu-build ng application para sa App Store at Google Play. Ang field na description ay ipinapakita sa mga resulta ng paghahanap ng package, kaya dapat itong maging informative at maglaman ng mga keyword upang mahanap ng ibang developers ang library.

Kung walang tamang pubspec.yaml, hindi mabubuo ang proyekto ng Flutter. Ang mga syntax error o maling indentation ay agad na nagdudulot ng compilation failure na may mensaheng Error on line X. Ang YAML ay sensitibo sa mga espasyo: isang dagdag na espasyo ay nagbabago sa structure ng data, at ang tabulation ay nagdudulot ng syntax error. Kaya kapag manu-manong nag-eedit ng pubspec.yaml, mahalagang gumamit ng editor na may YAML syntax highlighting, tulad ng VS Code na may opisyal na extension para sa Flutter.

Mga pangunahing seksyon ng pubspec.yaml

Ang pubspec.yaml ay binubuo ng mga mandatory at opsyonal na seksyon. Bawat seksyon ay responsable para sa isang partikular na aspeto ng configuration ng proyekto. Ang pagkakasunud-sunod ng mga seksyon ay hindi mahalaga, ngunit ayon sa convention ng komunidad, sinusunod ang hierarchy: metadata, environment, dependency, resources, platform.

name at description

Ang field na name ay nagtatakda ng natatanging identifier ng package sa snake_case format, na binubuo lamang ng maliliit na letrang Latin, numero, at underscore. Ang field na description — maikling paglalarawan ng proyekto hanggang 180 character, mandatory para sa paglalathala sa pub.dev. Ang paglalarawan ay dapat magpaliwanag ng layunin ng package, hindi inuulit ang pangalan, at naglalaman ng mga keyword para sa search optimization ng repository.

name: my_flutter_app
description: App para sa pamamahala ng mga gawain gamit ang Flutter
publish_to: 'none'

version at environment

Ang field na version ay gumagamit ng semantic versioning na major.minor.patch na may opsyonal na build number pagkatapos ng plus sign (1.0.0+1). Ang seksyon ng environment ay nagtatakda ng minimum at maximum na bersyon ng Dart at Flutter SDK para sa garantisadong compatibility. Kung ang bagong bersyon ng SDK ay naglalaman ng mga kritikal na pagbabago na hindi compatible sa code ng proyekto, ang compilation ay ititigil na may malinaw na error message.

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

dependencies at dev_dependencies

Ang seksyon ng dependencies ay naglilista ng mga package na kinakailangan para sa pagtakbo ng application sa runtime. Ang seksyon ng dev_dependencies ay naglalaman ng mga package para sa pagsubok, code generation, at pag-develop — hindi sila kasama sa release build. Ang paghihiwalay ng mga dependency ay kritikal para sa performance: bawat package sa dependencies ay nagpapalaki sa laki ng final APK o IPA, pati na rin sa startup time ng application dahil sa initialization ng mga karagdagang library.

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

Pagsasaayos ng assets at font

Ang seksyon ng flutter ay naglalaman ng mga subseksyon para sa pagsasaayos ng resources, font, at mga parameter ng platform. Ang resources ay ikinonekta sa pamamagitan ng array na paths na may pagtukoy ng mga partikular na file o buong directory. Lahat ng path ay tinutukoy relative sa root ng proyekto, hindi relative sa pubspec.yaml. Ito ay isang mahalagang nuance na madalas na nagdudulot ng kalituhan sa mga baguhan na Flutter developer.

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

Ang pagkonekta ng assets sa pamamagitan ng pubspec.yaml ay ginagawang accessible ang mga file sa pamamagitan ng AssetBundle sa runtime. Ito ay gumagana para sa mga larawan, JSON, text file, at iba pang resources. Awtomatikong sinusuportahan ng Flutter ang iba't ibang screen resolution: kung ilalagay mo ang images/2x/ at images/3x/, pipili ang Flutter ng tamang bersyon ng larawan batay sa device pixel ratio ng device. Para dito, sapat na na tukuyin sa assets ang root folder na images/ lamang.

Ang mga custom na font ay idinaragdag sa pamamagitan ng seksyong fonts na may pagtukoy ng family at listahan ng mga typeface. Pagkatapos baguhin ang pubspec.yaml, kailangang patakbuhin ang flutter pub get upang mailapat ang mga setting. Ang mga font ay maaaring gamitin parehong globally sa MaterialApp theme at locally sa mga partikular na widget. Para sa bawat typeface, maaaring tukuyin ang weight (100-900) at style (normal, italic), na nagpapahintulot sa Flutter na pumili ng tamang font file kapag gumagamit ng FontWeight at FontStyle sa code.

Pamamahala ng dependency at bersyon

Ang pub ay sumusuporta sa ilang paraan ng pagtukoy ng mga source ng dependency: pub.dev, Git repositories, local path, at private repositories. Ang pagpili ng source ay depende sa yugto ng pag-develop: para sa stable na bersyon, ginagamit ang pub.dev; para sa forks at custom modifications — Git; para sa parallel na binuong libraries — local path.

Ang operator na ^version ay nangangahulugang compatible na bersyon: ^1.2.0 ay nagpapahintulot ng mga bersyon >=1.2.0 at <2.0.0. Ito ay kahalintulad ng operator ~> sa CocoaPods at Caret operator sa npm. Awtomatikong nireresolba ng pub ang Dependency Hell sa pamamagitan ng SAT-solver algorithm na nakakahanap ng kombinasyon ng mga bersyon na nakakatugon sa lahat ng constraints. Kung walang ganoong kombinasyon, nagpapakita ang pub ng detalyadong mensahe na nagtutukoy ng mga conflicting package.

Ang file na pubspec.lock ay nagtatakda ng eksaktong bersyon ng mga dependency. Dapat itong itago sa version control system para sa mga application upang matiyak ang reproducible builds sa lahat ng machine ng team. Para sa mga library, ang pubspec.lock ay hindi kasama sa repository, dahil ang mga gumagamit ng library ay dapat magkaroon ng kakayahang gamitin ito sa iba't ibang bersyon ng mga dependency. Ang command na flutter pub upgrade ay nag-a-update ng lahat ng dependency ayon sa constraints ng pubspec.yaml, at ang flutter pub outdated ay nagpapakita kung aling mga package ang maaaring i-update.

Pagsasaayos ng pagbuo at paglalathala

Para sa paglalathala ng application sa pub.dev, ang mga setting ay tinutukoy sa seksyong publish_to. Ang value na 'none' ay nagbabawal sa hindi sinasadyang paglalathala ng package, na mahalaga para sa internal o hindi pampublikong proyekto. Kung wala ang publish_to, susubukan ng pub na ipalathala ang package sa default na pub.dev, na maaaring humantong sa hindi kanais-nais na pagtagas ng code.

Ang seksyong flutter ay naglalaman ng mga parameter ng platform: generate para sa awtomatikong pagbuo ng mga platform file at deferred-components para sa modular na pag-load ng functionality. Ang parameter na generate: true ay nagiging sanhi ng Flutter na awtomatikong lumikha at mag-update ng mga platform project (iOS, Android, Web) kapag nagdadagdag ng mga bagong platform sa pamamagitan ng flutter create --platforms. Kung wala ang parameter na ito, ang structure ng mga platform folder ay maaaring mawalan ng synchronization sa pubspec.yaml.

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

Ang seksyong platforms ay nagtatakda ng target na platform para sa package. Para sa mga application, ito ay awtomatikong tinutukoy kapag nagdadagdag ng suporta para sa isang partikular na platform sa pamamagitan ng flutter create. Ang mga platform ay maaaring idagdag at tanggalin nang manu-mano sa pamamagitan ng pag-edit ng pubspec.yaml. Ang Deferred Components ay nagpapahintulot sa pag-load ng mga bahagi ng application on demand, na binabawasan ang laki ng installation — ito ay partikular na mahalaga para sa mga laro at application na may maraming bihirang ginagamit na content.

Kapag naglalathala ng package, sinusuri ng pub ang lahat ng field ng pubspec.yaml para sa pagsunod sa mga kinakailangan ng repository. Ang kawalan ng mga mandatory field na name, version at description ay humahantong sa pagtanggi sa paglalathala. Bukod pa rito, sinusuri ang validity ng license, pagkakaroon ng README.md at CHANGELOG.md. Ang mga package na may error sa code analyzer (dart analyze) ay hindi rin pumapasa sa validation. Pagkatapos ng matagumpay na paglalathala, ang package ay magiging available sa pub.dev sa loob ng ilang minuto.

Ang seksyong dependency_overrides ay nagpapahintulot sa pagpilit ng bersyon ng package, hindi pinapansin ang mga constraint mula sa transitive dependencies. Ito ay isang makapangyarihan ngunit mapanganib na mekanismo: kung ginamit nang hindi tama, maaari itong humantong sa hindi pagkakatugma ng mga library. Gamitin lamang ang dependency_overrides pansamantala para sa pagresolba ng mga conflict o pagsubok ng mga bagong bersyon. Pagkatapos ayusin ang mga pangunahing dependency, dapat tanggalin ang override upang hindi makagambala sa dependency graph ng proyekto sa pangmatagalan.

Ang seksyong executables sa pubspec.yaml ay nagpapahintulot sa pagtukoy ng mga executable script na ini-install ng pub sa PATH kapag activated ang package. Ito ay kapaki-pakinabang para sa mga CLI tool na nakasulat sa Dart, halimbawa build_runner o dart_code_metrics. Ang command na dart pub global activate ay nag-i-install ng package nang globally, ginagawang available mula sa terminal ang mga script na tinukoy sa executables. Para sa mga application, ang executables ay karaniwang hindi ginagamit, dahil ang entry point ay tinutukoy sa pamamagitan ng main sa lib/main.dart.