pub: แนวคิดหลัก ตัวจัดการแพ็กเกจ Dart และ pubspec.yaml

pub คืออะไร?

pub (Package Universal Browser) — ตัวจัดการแพ็กเกจในตัวที่มาพร้อมกับ Dart SDK มันจัดการไลบรารีภายนอก แก้ไขข้อขัดแย้งของเวอร์ชัน ดาวน์โหลด transitive dependencies และแคชแพ็กเกจในเครื่อง ในระบบนิเวศของ Flutter นั้น pub ถูกใช้เป็นเครื่องมือหลักในการเชื่อมต่อปลั๊กอินนำทาง ไคลเอ็นต์ HTTP ตัวจัดการสถานะ และส่วนประกอบอื่น ๆ

ฟังก์ชันหลักของ pub รวมถึง: การติดตั้ง dependencies จากทะเบียน pub.dev, เส้นทางในเครื่อง (path dependencies) และ ที่เก็บ git; การแก้ไขเวอร์ชัน ตามกฎของการกำหนดเวอร์ชันเชิงความหมาย; การแคช แพ็กเกจที่ดาวน์โหลดในไดเรกทอรีระบบ; การเผยแพร่ แพ็กเกจของคุณเองในทะเบียนสาธารณะ การดำเนินการทั้งหมดนี้สามารถเข้าถึงได้ผ่านคำสั่ง CLI dart pub หรือคำสั่งที่เทียบเท่า flutter pub

สถาปัตยกรรมของ pub ใช้ กราฟ dependencies แบบปิด: ตัวจัดการสร้างต้นไม้ที่แต่ละแพ็กเกจปรากฏเพียงครั้งเดียว หากไลบรารีสองแห่งต้องการเวอร์ชันที่แตกต่างกันของแพ็กเกจเดียวกัน pub จะพยายามหาช่วงที่เข้ากันได้หรือรายงานข้อผิดพลาดข้อขัดแย้ง ซึ่งแตกต่างจากแนวทางของ npm ที่อนุญาตให้มีหลายเวอร์ชันของแพ็กเกจเดียวกันในโหนดต้นไม้ต่างกัน

โครงสร้าง pubspec.yaml

ไฟล์ pubspec.yaml — ไฟล์กำหนดค่าส่วนกลางของโปรเจกต์ Dart หรือ Flutter ใด ๆ มันเขียนในรูปแบบ YAML และมี metadata, dependencies, การกำหนดค่า build และข้อจำกัดของ SDK ด้านล่างเป็นตัวอย่างทั่วไปสำหรับแอปพลิเคชัน Flutter:

name: my_app
description: ตัวอย่างแอป Flutter
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/

ฟิลด์สำคัญของ pubspec.yaml: name — ชื่อแพ็กเกจที่ไม่ซ้ำกัน (เฉพาะภาษาละติน, ขีดล่าง, ตัวเลข); description — คำอธิบายสั้น ๆ (จำเป็นสำหรับการเผยแพร่); version — เวอร์ชันเชิงความหมายพร้อมหมายเลข build ที่เป็นตัวเลือกหลังเครื่องหมายบวก; environment — เวอร์ชันขั้นต่ำของ Dart SDK และ Flutter SDK; dependencies — dependencies หลักของแอปพลิเคชัน; dev_dependencies — dependencies สำหรับการพัฒนาและการทดสอบเท่านั้น; flutter — ส่วนกำหนดค่า Flutter (assets, ฟอนต์, ปลั๊กอิน)

ฟิลด์ publish_to ควบคุมความพร้อมในการเผยแพร่: ค่า none ห้ามการเผยแพร่ (โดยทั่วไปสำหรับแอปพลิเคชัน) ค่าเริ่มต้น — https://pub.dev ฟิลด์ dependency_overrides อนุญาตให้แทนที่เวอร์ชันแพ็กเกจโดยบังคับในสถานการณ์ที่มีข้อขัดแย้ง — ใช้ด้วยความระมัดระวัง เป็นเพียงวิธีแก้ปัญหาชั่วคราวเท่านั้น

dependencies และประเภทของมัน

pub รองรับ dependencies สี่ประเภท แต่ละประเภทระบุด้วยไวยากรณ์ของตัวเองภายใน pubspec.yaml:

โฮสต์ (hosted)

ประเภทมาตรฐาน — แพ็กเกจถูกดาวน์โหลดจากทะเบียน pub.dev หรือทะเบียนอื่นที่เข้ากันได้ ระบุชื่อแพ็กเกจและเวอร์ชัน ตัวอย่าง: http: ^1.1.0 จะดาวน์โหลดเวอร์ชันที่เข้ากันได้ล่าสุดจากช่วง >=1.1.0 และ <2.0.0 ตามกฎ caret versioning

SDK dependencies

ใช้สำหรับรวม Flutter SDK หรือ Dart SDK ไวยากรณ์: flutter: sdk: flutter แพ็กเกจถูกนำมาจากการติดตั้ง Flutter SDK ในเครื่อง ไม่ใช่จากทะเบียน SDK dependencies ไม่มีการกำหนดเวอร์ชัน — เวอร์ชันของมันถูกกำหนดโดยเวอร์ชัน Flutter ที่ติดตั้งอยู่ในปัจจุบัน

เส้นทาง (path)

ชี้ไปยังไดเรกทอรีในเครื่องที่มีแพ็กเกจ มีประโยชน์เมื่อพัฒนาไลบรารีและทดสอบโดยไม่ต้องเผยแพร่ ไวยากรณ์:

dependencies:
  my_local_lib:
    path: ../my_local_lib

path dependencies จะไม่ถูกกำหนดใน pubspec.lock — การอัปเดตแต่ละครั้งจะถูกแก้ไขใหม่จากเส้นทางที่ระบุ

Git

อนุญาตให้รวมแพ็กเกจโดยตรงจากที่เก็บ git รองรับสาขา แท็ก และ commit:

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

Git dependencies สะดวกสำหรับ fork, การแก้ไขที่ยังไม่ได้เผยแพร่ หรือการทำงานบน Pull Request แนะนำให้ระบุแท็กหรือ commit ที่เฉพาะเจาะจงแทนที่จะเป็นสาขาเพื่อหลีกเลี่ยงการเปลี่ยนแปลงที่ไม่คาดคิดระหว่างการ build

การกำหนดเวอร์ชันและช่วง

pub ปฏิบัติตาม Semantic Versioning 2.0 อย่างเคร่งครัด: รูปแบบ MAJOR.MINOR.PATCH โดยที่ MAJOR — การเปลี่ยนแปลงที่ไม่เข้ากันได้, MINOR — การเพิ่มที่เข้ากันได้ย้อนหลัง, PATCH — การแก้ไขที่เข้ากันได้ย้อนหลัง ตามโครงร่างนี้ pub กำหนดความเข้ากันได้ของแพ็กเกจและแก้ไขข้อขัดแย้ง

ตัวดำเนินการหลักสามตัวใช้ในการระบุเวอร์ชันใน pubspec.yaml:

• Caret (^) — ^1.2.3 เทียบเท่ากับ >=1.2.3 และ <2.0.0 ตัวดำเนินการที่พบบ่อยที่สุด เพราะมันหมายถึงความเข้ากันได้ภายในเวอร์ชันหลัก สำหรับแพ็กเกจที่มีเวอร์ชันหลัก 0 (ศูนย์) — ^0.1.2 หมายถึง >=0.1.2 และ <0.2.0 ซึ่งเป็นไปตามกฎ SemVer สำหรับเวอร์ชันที่ไม่เสถียร
• Tilde (~) — ~1.2.3 เทียบเท่ากับ >=1.2.3 และ <1.3.0 กำหนดเวอร์ชันรองให้คงที่ อนุญาตเฉพาะการอัปเดต patch ใช้น้อยกว่า ส่วนใหญ่เมื่อทราบว่ามีความไม่เข้ากันในระดับเวอร์ชันรอง
• ช่วงที่แน่นอน — >=1.2.0 <2.0.0 — รูปแบบที่ชัดเจนให้การควบคุมอย่างสมบูรณ์ มีประโยชน์สำหรับข้อจำกัดที่ซับซ้อน เช่น เมื่อใช้หลายเวอร์ชันของ transitive dependencies

หลังจากรัน dart pub get pub จะสร้างไฟล์ pubspec.lock ที่กำหนดเวอร์ชันที่แน่นอนของแพ็กเกจที่แก้ไขทั้งหมด (ทั้งทางตรงและทางอ้อม) ไฟล์นี้จะต้องรวมอยู่ในการควบคุมเวอร์ชันเพื่อให้แน่ใจว่าการ build ที่สามารถทำซ้ำได้บนทุกเครื่อง เมื่อรัน dart pub upgrade ไฟล์ล็อกจะถูกอัปเดตเป็นเวอร์ชันที่เข้ากันได้ล่าสุดภายใต้ข้อจำกัดที่ระบุ

ข้อผิดพลาด dependency conflict เกิดขึ้นเมื่อแพ็กเกจสองรายการต้องการช่วงที่ไม่ทับซ้อนกันของ dependency เดียวกัน pub รายงานว่าแพ็กเกจใดกำลังขัดแย้งและเพราะเหตุใด วิธีแก้ไข: อัปเดตแพ็กเกจที่ขัดแย้งหนึ่งรายการเป็นเวอร์ชันที่เข้ากันได้ ใช้ dependency_overrides (มาตรการชั่วคราว) หรือสลับไปใช้แพ็กเกจอื่น

คำสั่งหลักของ pub

การดำเนินการ pub ทั้งหมดดำเนินการผ่านอินเทอร์เฟซ CLI แบบรวม Dart SDK ใช้คำสั่ง dart pub Flutter SDK ใช้คำสั่งที่เทียบเท่า flutter pub (พิจารณา dependencies และปลั๊กอินของ Flutter SDK เพิ่มเติม) ด้านล่างเป็นคำสั่งสำคัญ:

• dart pub get — ดาวน์โหลด dependencies ทั้งหมดที่ระบุใน pubspec.yaml แก้ไขเวอร์ชันและสร้าง/อัปเดต pubspec.lock รันเมื่อ clone โปรเจกต์ครั้งแรกหรือหลังจากเปลี่ยน dependencies
• dart pub upgrade — อัปเดต dependencies ทั้งหมดเป็นเวอร์ชันล่าสุดภายใต้ข้อจำกัดของ pubspec.yaml และเขียนทับ pubspec.lock สามารถอัปเดตแพ็กเกจเดี่ยวได้: dart pub upgrade http
• dart pub add <package> — เพิ่ม dependency ใหม่ใน pubspec.yaml และรัน pub get ทันที ตัวอย่าง: dart pub add dio จะเพิ่มเวอร์ชันล่าสุดของแพ็กเกจ dio
• dart pub remove <package> — ลบ dependency ออกจาก pubspec.yaml และเริ่มการแก้ไขกราฟใหม่
• dart pub cache repair — โหลดแพ็กเกจที่แคชไว้ทั้งหมดใหม่ ช่วยเมื่อแคชในเครื่องเสียหายหรือเกิดข้อผิดพลาดของ checksum
• dart pub deps — แสดงแผนภาพ dependencies ในรูปแบบข้อความที่สะดวก มีประโยชน์สำหรับการวิเคราะห์ transitive dependencies และค้นหาซ้ำซ้อน
• dart pub publish — เผยแพร่แพ็กเกจปัจจุบันบน pub.dev ก่อนเผยแพร่ จะตรวจสอบความถูกต้องของ pubspec.yaml ใบอนุญาต และคำอธิบาย
• dart pub outdated — แสดงรายการ dependencies ที่ล้าสมัยพร้อมระบุเวอร์ชันปัจจุบัน เวอร์ชันที่ต้องการ และเวอร์ชันล่าสุดที่มี คล้ายกับ npm outdated

คำสั่งทั้งหมดยังมีอยู่ในรูปแบบย่อ dart pub get เป็น dart pub g (ไม่ใช่ทั้งหมด) ในโปรเจกต์ Flutter คำสั่งจะนำหน้าด้วย flutter: flutter pub get, flutter pub add และอื่น ๆ เวอร์ชัน Flutter ยังตรวจสอบความเข้ากันได้ของปลั๊กอินกับแพลตฟอร์มเป้าหมายเพิ่มเติม

การเผยแพร่บน pub.dev

pub.dev — ทะเบียนแพ็กเกจส่วนกลางของระบบนิเวศ Dart และ Flutter ณ เดือนมกราคม 2025 มีแพ็กเกจมากกว่า 50,000 รายการที่เผยแพร่ที่นั่น มียอดดาวน์โหลดรวมเกิน 10 พันล้านครั้ง แต่ละแพ็กเกจมีหน้าที่มีคำอธิบาย เอกสารประกอบ คะแนนความนิยม คะแนน Pub Points และเวอร์ชัน

Pub Points — ระบบประเมินคุณภาพแพ็กเกจอัตโนมัติตั้งแต่ 0 ถึง 130 คะแนน พิจารณาจาก: การมีใบอนุญาต คำอธิบาย ตัวอย่าง ความเข้ากันได้กับเวอร์ชันเสถียรล่าสุดของ Dart การไม่มีช่องโหว่ ความครอบคลุมของการทดสอบ ความถูกต้องของการจัดรูปแบบ คะแนนสูงช่วยเพิ่มการมองเห็นแพ็กเกจในการค้นหาและความไว้วางใจของผู้ใช้

กระบวนการเผยแพร่ประกอบด้วยหลายขั้นตอน:

1. ตรวจสอบ pubspec.yaml: ตรวจสอบให้แน่ใจว่ามี name, description, version, license (แนะนำให้ใช้รหัส SPDX เช่น MIT)
2. รัน dart pub publish --dry-run — จำลองการเผยแพร่โดยไม่ส่งไปยังเซิร์ฟเวอร์ แสดงไฟล์ทั้งหมดที่จะรวมในแพ็กเกจและข้อผิดพลาดที่อาจเกิดขึ้น
3. ยืนยันตัวตนผ่านบัญชี Google ในการเผยแพร่ครั้งแรก: dart pub publish จะเปิดเบราว์เซอร์สำหรับการยืนยันตัวตน OAuth
4. ยืนยันการเผยแพร่ในเทอร์มินัล หลังจากอัปโหลดสำเร็จ แพ็กเกจจะปรากฏบน pub.dev ภายในไม่กี่นาที

กฎสำคัญ: สามารถเผยแพร่ได้เฉพาะแพ็กเกจที่มี ชื่อไม่ซ้ำกัน เท่านั้น ไม่สามารถลบเวอร์ชันที่เผยแพร่แล้วได้ (สามารถซ่อนได้ด้วย dart pub unpublish ภายใน 7 วัน) สำหรับการอัปเดตใหญ่ ให้ปฏิบัติตามกฎ Semantic Versioning อย่าทำลาย API สาธารณะโดยไม่เปลี่ยนเวอร์ชันหลัก