pubspec.yaml — คืออะไร โครงสร้างและการกำหนดค่าการพึ่งพาใน Flutter

pubspec.yaml คืออะไร

pubspec.yaml เป็นไฟล์แมนิเฟสต์ในรูปแบบ YAML ที่ตัวจัดการแพ็กเกจ pub ใช้ในการจัดการโปรเจกต์ Dart และ Flutter ไฟล์นี้อยู่ในรูทของโปรเจกต์และถูกประมวลผลทุกคำสั่ง flutter pub get ต่างจากแพลตฟอร์มอื่นที่การกำหนดค่ากระจายอยู่ในหลายไฟล์ Flutter ใช้แมนิเฟสต์แบบรวมศูนย์เดียวสำหรับทุกความต้องการ

ไฟล์ประกอบด้วยข้อมูลเมตา: ชื่อโปรเจกต์ คำอธิบาย เวอร์ชัน ผู้เขียน ข้อมูลนี้ใช้เมื่อเผยแพร่แพ็กเกจบน pub.dev และเมื่อ build แอปพลิเคชันสำหรับ App Store และ Google Play ฟิลด์ description จะแสดงในผลการค้นหาแพ็กเกจ ดังนั้นจึงควรมีข้อมูลและมีคำสำคัญที่นักพัฒนาคนอื่นสามารถใช้ค้นหาไลบรารีได้

หากไม่มี pubspec.yaml ที่ถูกต้อง โปรเจกต์ Flutter จะไม่สามารถ build ได้ ข้อผิดพลาดทางไวยากรณ์หรือ การเยื้อง ที่ไม่ถูกต้องทำให้การคอมไพล์ล้มเหลวทันทีพร้อมข้อความ Error on line X YAML ไวต่อช่องว่าง: ช่องว่างที่เกินหนึ่งช่องเปลี่ยนโครงสร้างข้อมูล และแท็บทำให้เกิดข้อผิดพลาดทางไวยากรณ์ ดังนั้น เมื่อแก้ไข pubspec.yaml ด้วยตนเอง สิ่งสำคัญคือต้องใช้ตัวแก้ไขที่มีการเน้นไวยากรณ์ YAML เช่น VS Code ที่มีส่วนขยาย Flutter ทางการ

ส่วนหลักของ pubspec.yaml

pubspec.yaml ประกอบด้วยส่วนบังคับและส่วนเลือกได้ แต่ละส่วนรับผิดชอบด้านเฉพาะของ การกำหนดค่า โปรเจกต์ ลำดับของส่วนไม่สำคัญ แต่ตามธรรมเนียมของชุมชนจะปฏิบัติตามลำดับชั้น: ข้อมูลเมตา สภาพแวดล้อม การพึ่งพา ทรัพยากร แพลตฟอร์ม

name และ description

ฟิลด์ name กำหนดตัวระบุแพ็กเกจที่ไม่ซ้ำกันในรูปแบบ snake_case ซึ่งประกอบด้วยเฉพาะตัวอักษรละตินพิมพ์เล็ก ตัวเลข และขีดล่าง ฟิลด์ description เป็นสรุปโปรเจกต์โดยย่อสูงสุด 180 ตัวอักษร ซึ่งจำเป็นสำหรับการเผยแพร่บน pub.dev คำอธิบายควรอธิบายวัตถุประสงค์ของแพ็กเกจโดยไม่ซ้ำชื่อ และมีคำสำคัญสำหรับการปรับแต่งการค้นหาของ repository

name: my_flutter_app
description: แอปจัดการงานด้วย Flutter
publish_to: 'none'

version และ environment

ฟิลด์ version ใช้การกำหนดเวอร์ชันเชิงความหมาย major.minor.patch พร้อมหมายเลข build ไม่บังคับหลังเครื่องหมายบวก (1.0.0+1) ส่วน environment กำหนดเวอร์ชันต่ำสุดและสูงสุดของ Dart และ Flutter SDK เพื่อรับประกันความเข้ากันได้ หากเวอร์ชันใหม่ของ SDK มีการเปลี่ยนแปลงที่ไม่เข้ากันกับโค้ดของโปรเจกต์ การ build จะหยุดด้วยข้อความข้อผิดพลาดที่ชัดเจน

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

dependencies และ dev_dependencies

ส่วน dependencies แสดงรายการแพ็กเกจที่จำเป็นสำหรับแอปพลิเคชันในการทำงานขณะรันไทม์ ส่วน dev_dependencies มีแพ็กเกจสำหรับการทดสอบ การสร้างโค้ด และการพัฒนา — แพ็กเกจเหล่านี้จะไม่รวมอยู่ใน build ที่เผยแพร่ การแยกการพึ่งพามีความสำคัญต่อประสิทธิภาพ: แต่ละแพ็กเกจใน dependencies เพิ่มขนาด APK หรือ IPA สุดท้าย รวมถึงเวลาเริ่มต้นแอปพลิเคชันเนื่องจากการเริ่มต้นไลบรารีเพิ่มเติม

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

การกำหนดค่าแอสเซ็ตและฟอนต์

ส่วน flutter มีส่วนย่อยสำหรับกำหนดค่าทรัพยากร ฟอนต์ และพารามิเตอร์แพลตฟอร์ม ทรัพยากรเชื่อมต่อผ่านอาร์เรย์ paths ที่ระบุไฟล์เฉพาะหรือไดเรกทอรีทั้งหมด เส้นทางทั้งหมดระบุสัมพันธ์กับรูทของโปรเจกต์ ไม่ใช่สัมพันธ์กับ pubspec.yaml นี่เป็นความแตกต่างสำคัญที่มักทำให้นักพัฒนา 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

การเชื่อมต่อ แอสเซ็ต ผ่าน pubspec.yaml ทำให้ไฟล์สามารถเข้าถึงได้ผ่าน AssetBundle ขณะรันไทม์ ซึ่งทำงานสำหรับรูปภาพ JSON ไฟล์ข้อความ และทรัพยากรอื่นใด Flutter รองรับความละเอียดหน้าจอที่แตกต่างกันโดยอัตโนมัติ: หากคุณเพิ่ม images/2x/ และ images/3x/ Flutter จะเลือกรูปภาพเวอร์ชันที่เหมาะสมตามอัตราส่วนพิกเซลของอุปกรณ์ การทำเช่นนี้ เพียงระบุเฉพาะโฟลเดอร์รูท images/ ใน assets ก็เพียงพอ

ฟอนต์ ที่กำหนดเองถูกเพิ่มผ่านส่วน fonts ด้วยชื่อตระกูลและรายการรูปแบบ หลังจากแก้ไข pubspec.yaml คุณต้องเรียกใช้ flutter pub get เพื่อใช้การเปลี่ยนแปลง ฟอนต์สามารถใช้ทั้งในระดับโลกในธีม MaterialApp และในระดับท้องถิ่นในวิดเจ็ตเฉพาะ สำหรับแต่ละรูปแบบ คุณสามารถระบุ weight (100–900) และ style (normal, italic) ซึ่งช่วยให้ Flutter เลือกไฟล์ฟอนต์ที่ถูกต้องเมื่อใช้ FontWeight และ FontStyle ในโค้ด

การจัดการการพึ่งพาและเวอร์ชัน

pub รองรับหลายวิธีในการระบุ แหล่งที่มา ของการพึ่งพา: pub.dev, พื้นที่เก็บ Git, เส้นทางท้องถิ่น และพื้นที่เก็บส่วนตัว การเลือกแหล่งที่มาขึ้นอยู่กับขั้นตอนการพัฒนา: สำหรับเวอร์ชันเสถียรใช้ pub.dev สำหรับ fork และการปรับแต่งเฉพาะ — Git สำหรับไลบรารีที่พัฒนาควบคู่กัน — เส้นทางท้องถิ่น

ตัวดำเนินการ ^version หมายถึงเวอร์ชันที่เข้ากันได้: ^1.2.0 อนุญาตเวอร์ชัน >=1.2.0 และ <2.0.0 ซึ่งคล้ายกับตัวดำเนินการ ~> ใน CocoaPods และตัวดำเนินการ Caret ใน npm pub แก้ปัญหา Dependency Hell โดยอัตโนมัติผ่านอัลกอริทึม SAT solver ที่ค้นหาชุดเวอร์ชันที่ตรงตามข้อจำกัดทั้งหมด หากไม่มีชุดดังกล่าว pub จะแสดงข้อความโดยละเอียดระบุแพ็กเกจที่ขัดแย้งกัน

ไฟล์ pubspec.lock ล็อกเวอร์ชันที่แน่นอนของการพึ่งพา ควรเก็บไว้ในระบบควบคุมเวอร์ชันสำหรับแอปพลิเคชันเพื่อรับประกัน build ที่ทำซ้ำได้บนเครื่องทั้งหมดของทีม สำหรับไลบรารี ไม่รวม pubspec.lock ในพื้นที่เก็บ เพราะผู้ใช้ไลบรารีควรสามารถใช้มันกับเวอร์ชันการพึ่งพาที่แตกต่างกัน คำสั่ง flutter pub upgrade อัปเดตการพึ่งพาทั้งหมดตามข้อจำกัดของ pubspec.yaml ในขณะที่ flutter pub outdated แสดงแพ็กเกจที่สามารถอัปเดตได้

การกำหนดค่า build และการเผยแพร่

ในการเผยแพร่แอปพลิเคชันบน pub.dev การตั้งค่าจะถูกระบุในส่วน publish_to ค่า 'none' ป้องกันการเผยแพร่แพ็กเกจโดยไม่ตั้งใจ ซึ่งสำคัญสำหรับโปรเจกต์ภายในหรือไม่สาธารณะ หากไม่มี publish_to pub จะพยายามเผยแพร่แพ็กเกจบน pub.dev เริ่มต้น ซึ่งอาจนำไปสู่การรั่วไหลของโค้ดที่ไม่พึงประสงค์

ส่วน flutter มีพารามิเตอร์แพลตฟอร์ม: generate สำหรับการสร้างไฟล์แพลตฟอร์มอัตโนมัติ และ deferred-components สำหรับการโหลดฟังก์ชันแบบโมดูลาร์ พารามิเตอร์ generate: true บังคับให้ Flutter สร้างและอัปเดตโปรเจกต์แพลตฟอร์ม (iOS, Android, Web) โดยอัตโนมัติเมื่อเพิ่มแพลตฟอร์มใหม่ผ่าน flutter create --platforms หากไม่มีพารามิเตอร์นี้ โครงสร้างโฟลเดอร์แพลตฟอร์มอาจไม่ซิงค์กับ pubspec.yaml

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

ส่วน platforms กำหนดแพลตฟอร์มเป้าหมายสำหรับแพ็กเกจ สำหรับแอปพลิเคชัน จะถูกกำหนดโดยอัตโนมัติเมื่อเพิ่มการสนับสนุนแพลตฟอร์มเฉพาะผ่าน flutter create แพลตฟอร์มสามารถเพิ่มและลบได้ด้วยตนเองโดยการแก้ไข pubspec.yaml คอมโพเนนต์ที่รอการโหลด (Deferred Components) อนุญาตให้โหลดส่วนต่าง ๆ ของแอปพลิเคชันตามต้องการ ลดขนาดการติดตั้ง — ซึ่งเกี่ยวข้องโดยเฉพาะกับเกมและแอปพลิเคชันที่มีเนื้อหาที่ไม่ค่อยได้ใช้จำนวนมาก

เมื่อเผยแพร่แพ็กเกจ pub จะตรวจสอบว่าฟิลด์ทั้งหมดของ pubspec.yaml เป็นไปตาม ข้อกำหนด ของพื้นที่เก็บ การไม่มีฟิลด์บังคับ name, version และ description ส่งผลให้การเผยแพร่ถูกปฏิเสธ นอกจากนี้ ยังตรวจสอบความถูกต้องของใบอนุญาตและการมีอยู่ของ README.md และ CHANGELOG.md แพ็กเกจที่มีข้อผิดพลาดของตัววิเคราะห์โค้ด (dart analyze) ก็ไม่ผ่านการตรวจสอบเช่นกัน หลังจากการเผยแพร่สำเร็จ แพ็กเกจจะพร้อมใช้งานบน pub.dev ภายในไม่กี่นาที

ส่วน dependency_overrides อนุญาตให้บังคับเวอร์ชันแพ็กเกจเฉพาะ โดยไม่สนใจข้อจำกัดจากการพึ่งพาแบบช่วงต่อ นี่เป็นกลไกที่ทรงพลังแต่อันตราย: หากใช้ไม่ถูกต้อง อาจนำไปสู่ความไม่เข้ากันของไลบรารี ใช้ dependency_overrides ชั่วคราวเท่านั้นเพื่อแก้ไขข้อขัดแย้งหรือทดสอบเวอร์ชันใหม่ หลังจากแก้ไขการพึ่งพาหลักแล้ว ควรลบการแทนที่เพื่อไม่ให้ทำลายกราฟการพึ่งพาของโปรเจกต์ในระยะยาว

ส่วน executables ใน pubspec.yaml อนุญาตให้ระบุสคริปต์ที่ปฏิบัติการได้ซึ่ง pub ติดตั้งใน PATH เมื่อเปิดใช้งานแพ็กเกจ ซึ่งมีประโยชน์สำหรับเครื่องมือ CLI ที่เขียนด้วย Dart เช่น build_runner หรือ dart_code_metrics คำสั่ง dart pub global activate ติดตั้งแพ็กเกจในระดับโลก ทำให้สคริปต์ที่ระบุใน executables สามารถเข้าถึงได้จากเทอร์มินัล สำหรับแอปพลิเคชัน มักจะไม่ใช้ executables เนื่องจากจุดเริ่มต้นถูกกำหนดผ่าน main ใน lib/main.dart