pub: các khái niệm chính, trình quản lý gói Dart và pubspec.yaml

pub là gì?

pub (Package Universal Browser) — trình quản lý gói tích hợp sẵn đi kèm với Dart SDK. Nó quản lý thư viện bên ngoài, giải quyết xung đột phiên bản, tải xuống phụ thuộc chuyển tiếp và lưu gói vào bộ nhớ đệm cục bộ. Trong hệ sinh thái Flutter, pub được sử dụng làm công cụ chính để kết nối plugin điều hướng, trình khách HTTP, trình quản lý trạng thái và các thành phần khác.

Các chức năng chính của pub bao gồm: cài đặt phụ thuộc từ sổ đăng ký pub.dev, đường dẫn cục bộ (phụ thuộc đường dẫn) và kho git; giải quyết phiên bản theo quy tắc quản lý phiên bản ngữ nghĩa; lưu bộ nhớ đệm các gói đã tải xuống trong thư mục hệ thống; xuất bản gói riêng lên sổ đăng ký công khai. Tất cả các thao tác này đều có sẵn qua lệnh CLI dart pub hoặc lệnh tương đương flutter pub.

Kiến trúc của pub dựa trên đồ thị phụ thuộc khép kín: trình quản lý xây dựng một cây nơi mỗi gói xuất hiện đúng một lần. Nếu hai thư viện yêu cầu các phiên bản khác nhau của cùng một gói, pub cố gắng tìm một phạm vi tương thích hoặc báo lỗi xung đột. Điều này khác với cách tiếp cận của npm, cho phép nhiều phiên bản của cùng một gói trong các nút cây khác nhau.

Cấu trúc pubspec.yaml

Tệp pubspec.yaml — tệp cấu hình trung tâm của bất kỳ dự án Dart hoặc Flutter nào. Nó được viết bằng định dạng YAML và chứa siêu dữ liệu, phụ thuộc, cấu hình xây dựng và ràng buộc SDK. Dưới đây là ví dụ điển hình cho ứng dụng Flutter:

name: my_app
description: Ví dụ về ứng dụng 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/

Các trường chính của pubspec.yaml: name — tên gói duy nhất (chữ Latinh, gạch dưới, chữ số); description — mô tả ngắn gọn (bắt buộc để xuất bản); version — phiên bản ngữ nghĩa với số bản dựng tùy chọn sau dấu cộng; environment — phiên bản tối thiểu của Dart SDK và Flutter SDK; dependencies — phụ thuộc chính của ứng dụng; dev_dependencies — phụ thuộc chỉ dành cho phát triển và kiểm thử; flutter — phần cấu hình Flutter (tài nguyên, phông chữ, plugin).

Trường publish_to kiểm soát khả năng xuất bản: giá trị none cấm xuất bản (điển hình cho ứng dụng), giá trị mặc định — https://pub.dev. Trường dependency_overrides cho phép ghi đè cưỡng bức phiên bản gói trong tình huống xung đột — sử dụng thận trọng, chỉ như giải pháp tạm thời.

Phụ thuộc và các loại

pub hỗ trợ bốn loại phụ thuộc, mỗi loại được chỉ định bằng cú pháp riêng trong pubspec.yaml:

Được lưu trữ (hosted)

Loại tiêu chuẩn — gói được tải xuống từ sổ đăng ký pub.dev hoặc sổ đăng ký tương thích khác. Chỉ định tên gói và phiên bản. Ví dụ: http: ^1.1.0 sẽ tải xuống phiên bản tương thích mới nhất từ phạm vi >=1.1.0 và <2.0.0 theo quy tắc caret versioning.

Phụ thuộc SDK

Được sử dụng để bao gồm Flutter SDK hoặc Dart SDK. Cú pháp: flutter: sdk: flutter. Gói được lấy từ cài đặt Flutter SDK cục bộ, không phải từ sổ đăng ký. Phụ thuộc SDK không được quản lý phiên bản — phiên bản của chúng được xác định bởi phiên bản Flutter hiện đang cài đặt.

Đường dẫn (path)

Trỏ đến thư mục cục bộ chứa gói. Hữu ích khi phát triển thư viện và kiểm thử mà không cần xuất bản. Cú pháp:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Phụ thuộc đường dẫn không được cố định trong pubspec.lock — mỗi lần cập nhật được giải quyết lại từ đường dẫn đã chỉ định.

Git

Cho phép bao gồm gói trực tiếp từ kho git. Hỗ trợ nhánh, thẻ và commit:

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

Phụ thuộc git thuận tiện cho fork, bản sửa lỗi chưa xuất bản hoặc làm việc trên Pull Request. Nên chỉ định thẻ hoặc commit cụ thể thay vì nhánh để tránh thay đổi bất ngờ trong quá trình xây dựng.

Quản lý phiên bản và phạm vi

pub tuân thủ nghiêm ngặt Semantic Versioning 2.0: định dạng MAJOR.MINOR.PATCH, trong đó MAJOR — thay đổi không tương thích, MINOR — bổ sung tương thích ngược, PATCH — sửa lỗi tương thích ngược. Dựa trên sơ đồ này, pub xác định tính tương thích của gói và giải quyết xung đột.

Ba toán tử chính được sử dụng để chỉ định phiên bản trong pubspec.yaml:

• Caret (^) — ^1.2.3 tương đương >=1.2.3 và <2.0.0. Toán tử phổ biến nhất, vì nó ngụ ý tương thích trong phiên bản chính. Đối với gói có phiên bản chính 0 (không) — ^0.1.2 có nghĩa >=0.1.2 và <0.2.0, tuân theo quy tắc SemVer cho phiên bản không ổn định.
• Tilde (~) — ~1.2.3 tương đương >=1.2.3 và <1.3.0. Cố định phiên bản phụ, chỉ cho phép cập nhật patch. Ít được sử dụng hơn, chủ yếu khi biết không tương thích ở cấp phiên bản phụ.
• Phạm vi chính xác — >=1.2.0 <2.0.0 — ký hiệu rõ ràng cung cấp toàn quyền kiểm soát. Hữu ích cho các ràng buộc phức tạp, ví dụ khi sử dụng nhiều phiên bản của phụ thuộc chuyển tiếp.

Sau khi chạy dart pub get, pub tạo ra tệp pubspec.lock cố định phiên bản chính xác của tất cả các gói đã giải quyết (trực tiếp và chuyển tiếp). Tệp này phải được đưa vào kiểm soát phiên bản để đảm bảo xây dựng tái tạo được trên tất cả máy. Khi chạy dart pub upgrade, tệp lock được cập nhật lên phiên bản tương thích mới nhất trong các ràng buộc đã chỉ định.

Lỗi xung đột phụ thuộc xảy ra khi hai gói yêu cầu phạm vi không chồng chéo của cùng một phụ thuộc. pub báo cáo gói nào đang xung đột và lý do. Giải pháp: cập nhật một trong các gói xung đột lên phiên bản tương thích, sử dụng dependency_overrides (biện pháp tạm thời) hoặc chuyển sang gói thay thế.

Lệnh pub chính

Tất cả thao tác pub được thực hiện qua giao diện CLI thống nhất. Dart SDK sử dụng lệnh dart pub, Flutter SDK sử dụng lệnh tương đương flutter pub (có tính thêm phụ thuộc và plugin Flutter SDK). Dưới đây là các lệnh chính:

• dart pub get — tải xuống tất cả phụ thuộc được chỉ định trong pubspec.yaml, giải quyết phiên bản và tạo/cập nhật pubspec.lock. Chạy khi clone dự án lần đầu hoặc sau khi thay đổi phụ thuộc.
• dart pub upgrade — cập nhật tất cả phụ thuộc lên phiên bản mới nhất trong ràng buộc của pubspec.yaml và ghi đè pubspec.lock. Có thể cập nhật gói riêng lẻ: dart pub upgrade http.
• dart pub add <package> — thêm phụ thuộc mới vào pubspec.yaml và chạy ngay pub get. Ví dụ: dart pub add dio thêm phiên bản mới nhất của gói dio.
• dart pub remove <package> — xóa phụ thuộc khỏi pubspec.yaml và khởi động lại giải quyết đồ thị.
• dart pub cache repair — tải lại tất cả gói trong bộ nhớ đệm. Hữu ích khi bộ nhớ đệm cục bộ bị hỏng hoặc lỗi tổng kiểm tra.
• dart pub deps — hiển thị cây phụ thuộc ở định dạng văn bản tiện lợi. Hữu ích để phân tích phụ thuộc chuyển tiếp và tìm trùng lặp.
• dart pub publish — xuất bản gói hiện tại lên pub.dev. Trước khi xuất bản, xác thực pubspec.yaml, giấy phép và mô tả.
• dart pub outdated — hiển thị danh sách phụ thuộc lỗi thời với phiên bản hiện tại, mong muốn và mới nhất có sẵn. Tương tự npm outdated.

Tất cả lệnh cũng có sẵn ở dạng rút gọn dart pub get như dart pub g (không phải tất cả). Trong dự án Flutter, lệnh được thêm tiền tố flutter: flutter pub get, flutter pub add, v.v. Phiên bản Flutter còn kiểm tra thêm tính tương thích của plugin với nền tảng mục tiêu.

Xuất bản trên pub.dev

pub.dev — sổ đăng ký gói trung tâm của hệ sinh thái Dart và Flutter. Tính đến tháng 1 năm 2025, hơn 50.000 gói đã được xuất bản ở đó, với tổng số lượt tải xuống vượt quá 10 tỷ. Mỗi gói có trang với mô tả, tài liệu, điểm phổ biến, điểm Pub Points và phiên bản.

Pub Points — hệ thống đánh giá chất lượng gói tự động từ 0 đến 130 điểm. Nó xem xét: sự hiện diện của giấy phép, mô tả, ví dụ, tương thích với phiên bản Dart ổn định mới nhất, không có lỗ hổng bảo mật, mức độ phủ kiểm thử, định dạng chính xác. Điểm cao giúp tăng khả năng hiển thị của gói trong tìm kiếm và niềm tin của người dùng.

Quy trình xuất bản bao gồm một số bước:

1. Kiểm tra pubspec.yaml: đảm bảo name, description, version, license có mặt (khuyến nghị mã SPDX, ví dụ MIT).
2. Chạy dart pub publish --dry-run — mô phỏng xuất bản mà không gửi lên máy chủ, hiển thị tất cả tệp sẽ được đưa vào gói và lỗi có thể xảy ra.
3. Xác thực qua tài khoản Google khi xuất bản lần đầu: dart pub publish sẽ mở trình duyệt để xác thực OAuth.
4. Xác nhận xuất bản trong thiết bị đầu cuối. Sau khi tải lên thành công, gói sẽ xuất hiện trên pub.dev trong vòng vài phút.

Quy tắc quan trọng: chỉ có thể xuất bản gói có tên duy nhất; phiên bản đã xuất bản không thể xóa (chỉ có thể ẩn — dart pub unpublish — trong vòng 7 ngày); đối với cập nhật lớn, tuân theo quy tắc Semantic Versioning, không phá vỡ API công khai mà không thay đổi phiên bản chính.