pubspec.yaml — khái niệm, cấu trúc và cấu hình phụ thuộc trong Flutter

pubspec.yaml là gì

pubspec.yaml là tệp kê khai ở định dạng YAML mà trình quản lý gói pub sử dụng để quản lý dự án Dart và Flutter. Nó nằm ở thư mục gốc của dự án và được xử lý mỗi khi chạy lệnh flutter pub get. Không giống như các nền tảng khác nơi cấu hình được phân tán qua nhiều tệp, Flutter sử dụng một tệp kê khai tập trung duy nhất cho mọi nhu cầu.

Tệp chứa siêu dữ liệu: tên dự án, mô tả, phiên bản, tác giả. Dữ liệu này được sử dụng khi xuất bản gói lên pub.dev và khi xây dựng ứng dụng cho App Store và Google Play. Trường description được hiển thị trong kết quả tìm kiếm gói, vì vậy nó phải mang tính thông tin và chứa từ khóa để các nhà phát triển khác có thể tìm thấy thư viện.

Nếu không có pubspec.yaml chính xác, dự án Flutter không thể được xây dựng. Lỗi cú pháp hoặc thụt lề không đúng dẫn đến lỗi biên dịch ngay lập tức với thông báo Error on line X. YAML nhạy cảm với khoảng trắng: một khoảng trắng thừa làm thay đổi cấu trúc dữ liệu và tab gây ra lỗi cú pháp. Do đó, khi chỉnh sửa pubspec.yaml thủ công, điều quan trọng là sử dụng trình soạn thảo có tô sáng cú pháp YAML, như VS Code với tiện ích mở rộng Flutter chính thức.

Các phần chính của pubspec.yaml

pubspec.yaml bao gồm các phần bắt buộc và tùy chọn. Mỗi phần chịu trách nhiệm cho một khía cạnh cụ thể của cấu hình dự án. Thứ tự các phần không quan trọng, nhưng theo quy ước cộng đồng, thứ tự phân cấp là: siêu dữ liệu, môi trường, phụ thuộc, tài nguyên, nền tảng.

name và description

Trường name đặt định danh gói duy nhất ở định dạng snake_case, chỉ bao gồm chữ Latinh thường, chữ số và gạch dưới. Trường description là bản tóm tắt ngắn gọn dự án tối đa 180 ký tự, bắt buộc để xuất bản trên pub.dev. Mô tả phải giải thích mục đích của gói mà không lặp lại tên và chứa từ khóa để tối ưu hóa tìm kiếm kho lưu trữ.

name: my_flutter_app
description: Ứng dụng quản lý tác vụ với Flutter
publish_to: 'none'

version và environment

Trường version sử dụng quản lý phiên bản ngữ nghĩa major.minor.patch với số bản dựng tùy chọn sau dấu cộng (1.0.0+1). Phần environment đặt phiên bản tối thiểu và tối đa của SDK Dart và Flutter để đảm bảo tương thích. Nếu phiên bản SDK mới chứa các thay đổi không tương thích với mã dự án, quá trình xây dựng sẽ dừng lại với thông báo lỗi rõ ràng.

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

dependencies và dev_dependencies

Phần dependencies liệt kê các gói cần thiết để ứng dụng chạy trong thời gian chạy. Phần dev_dependencies chứa các gói để kiểm thử, tạo mã và phát triển — chúng không được đưa vào bản dựng phát hành. Việc tách biệt phụ thuộc rất quan trọng cho hiệu suất: mỗi gói trong dependencies làm tăng kích thước APK hoặc IPA cuối cùng, cũng như thời gian khởi động ứng dụng do khởi tạo các thư viện bổ sung.

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

Cấu hình tài nguyên và phông chữ

Phần flutter chứa các phần phụ để cấu hình tài nguyên, phông chữ và tham số nền tảng. Tài nguyên được kết nối qua mảng paths chỉ định các tệp cụ thể hoặc toàn bộ thư mục. Tất cả đường dẫn được chỉ định tương đối so với thư mục gốc dự án, không phải tương đối so với pubspec.yaml. Đây là một sắc thái quan trọng thường gây nhầm lẫn cho các nhà phát triển Flutter mới bắt đầu.

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

Kết nối tài nguyên qua pubspec.yaml làm cho các tệp có thể truy cập được qua AssetBundle trong thời gian chạy. Điều này hoạt động với hình ảnh, JSON, tệp văn bản và bất kỳ tài nguyên nào khác. Flutter tự động hỗ trợ các độ phân giải màn hình khác nhau: nếu bạn thêm images/2x/ và images/3x/, Flutter sẽ chọn phiên bản hình ảnh phù hợp dựa trên tỷ lệ pixel thiết bị. Để làm điều này, chỉ cần chỉ định trong assets thư mục gốc images/.

Phông chữ tùy chỉnh được thêm qua phần fonts với tên họ và danh sách kiểu. Sau khi sửa đổi pubspec.yaml, bạn cần chạy flutter pub get để áp dụng các thay đổi. Phông chữ có thể được sử dụng toàn cục trong chủ đề MaterialApp hoặc cục bộ trong các widget cụ thể. Cho mỗi kiểu, bạn có thể chỉ định weight (100–900) và style (normal, italic), cho phép Flutter chọn đúng tệp phông chữ khi sử dụng FontWeight và FontStyle trong mã.

Quản lý phụ thuộc và phiên bản

pub hỗ trợ nhiều cách để chỉ định nguồn phụ thuộc: pub.dev, kho lưu trữ Git, đường dẫn cục bộ và kho lưu trữ riêng tư. Việc chọn nguồn phụ thuộc vào giai đoạn phát triển: cho phiên bản ổn định sử dụng pub.dev, cho fork và sửa đổi tùy chỉnh — Git, cho thư viện đang phát triển song song — đường dẫn cục bộ.

Toán tử ^version chỉ phiên bản tương thích: ^1.2.0 cho phép phiên bản >=1.2.0 và <2.0.0. Điều này tương tự như toán tử ~> trong CocoaPods và toán tử Caret trong npm. pub tự động giải quyết Dependency Hell thông qua thuật toán SAT solver để tìm tổ hợp phiên bản thỏa mãn tất cả ràng buộc. Nếu không có tổ hợp nào tồn tại, pub sẽ xuất thông báo chi tiết chỉ ra các gói xung đột.

Tệp pubspec.lock khóa các phiên bản chính xác của phụ thuộc. Nó nên được lưu trữ trong hệ thống kiểm soát phiên bản cho ứng dụng để đảm bảo các bản dựng tái tạo được trên tất cả máy của nhóm. Đối với thư viện, pubspec.lock không được đưa vào kho lưu trữ, vì người dùng thư viện cần có thể sử dụng nó với các phiên bản phụ thuộc khác nhau. Lệnh flutter pub upgrade cập nhật tất cả phụ thuộc theo ràng buộc của pubspec.yaml, trong khi flutter pub outdated hiển thị các gói có thể cập nhật.

Cấu hình xây dựng và xuất bản

Để xuất bản ứng dụng lên pub.dev, cài đặt được chỉ định trong phần publish_to. Giá trị 'none' ngăn chặn việc xuất bản gói vô tình, điều này quan trọng cho các dự án nội bộ hoặc không công khai. Nếu publish_to bị thiếu, pub sẽ cố gắng xuất bản gói lên pub.dev mặc định, điều này có thể dẫn đến rò rỉ mã không mong muốn.

Phần flutter bao gồm các tham số nền tảng: generate để tự động tạo tệp nền tảng, và deferred-components để tải chức năng theo mô-đun. Tham số generate: true buộc Flutter tự động tạo và cập nhật các dự án nền tảng (iOS, Android, Web) khi thêm nền tảng mới qua flutter create --platforms. Không có tham số này, cấu trúc thư mục nền tảng có thể mất đồng bộ với pubspec.yaml.

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

Phần platforms đặt các nền tảng mục tiêu cho gói. Đối với ứng dụng, nó được xác định tự động khi thêm hỗ trợ cho nền tảng cụ thể qua flutter create. Các nền tảng có thể được thêm và xóa thủ công bằng cách chỉnh sửa pubspec.yaml. Deferred Components cho phép tải các phần của ứng dụng theo yêu cầu, giảm kích thước cài đặt — điều này đặc biệt phù hợp cho trò chơi và ứng dụng có lượng lớn nội dung ít khi sử dụng.

Khi xuất bản gói, pub kiểm tra tất cả trường của pubspec.yaml tuân thủ yêu cầu của kho lưu trữ. Việc thiếu các trường bắt buộc name, version và description dẫn đến từ chối xuất bản. Ngoài ra, tính chính xác của giấy phép và sự hiện diện của README.md và CHANGELOG.md được kiểm tra. Các gói có lỗi phân tích mã (dart analyze) cũng không vượt qua được xác thực. Sau khi xuất bản thành công, gói sẽ có sẵn trên pub.dev trong vòng vài phút.

Phần dependency_overrides cho phép buộc chỉ định phiên bản gói cụ thể, bỏ qua các ràng buộc từ phụ thuộc truyền dẫn. Đây là cơ chế mạnh mẽ nhưng nguy hiểm: nếu sử dụng không đúng, nó có thể dẫn đến không tương thích thư viện. Chỉ sử dụng dependency_overrides tạm thời để giải quyết xung đột hoặc kiểm thử phiên bản mới. Sau khi sửa phụ thuộc chính, nên loại bỏ ghi đè để tránh phá vỡ đồ thị phụ thuộc của dự án về lâu dài.

Phần executables trong pubspec.yaml cho phép chỉ định các tập lệnh thực thi mà pub cài đặt vào PATH khi kích hoạt gói. Điều này hữu ích cho các công cụ CLI viết bằng Dart, như build_runner hoặc dart_code_metrics. Lệnh dart pub global activate cài đặt gói toàn cục, làm cho các tập lệnh được chỉ định trong executables có thể truy cập từ thiết bị đầu cuối. Đối với ứng dụng, executables thường không được sử dụng, vì điểm vào được xác định qua main trong lib/main.dart.