Swift Package Manager giờ là mặc định — và CocoaPods đã có hạn chót

Phần lớn lập trình viên Flutter đã migrate sang Swift Package Manager mà không hay biết. Nó bật mặc định từ Flutter 3.44, và tooling tự thêm phần tích hợp vào project Xcode ngay lần build đầu sau khi nâng cấp. Lý do phải để ý lúc này là một cái mốc: registry CocoaPods chuyển sang chỉ đọc ngày 02/12/2026. Sau mốc đó, việc tắt SwiftPM không còn là lối thoát được hỗ trợ.

Flutter 3.47 công bố 92 trong 100 plugin iOS phổ biến nhất đã chuyển sang Swift Package Manager. Cái đuôi dài mới là thứ cắn bạn, không phải phần đầu phân phối.

Thực sự thay đổi gì trong project của bạn

Khi SwiftPM bật và bạn build, Flutter sửa project Xcode theo ba cách:

Thêm FlutterGeneratedPluginSwiftPackage làm package dependency của target Runner.
Thêm pre-action Run Prepare Flutter Framework Script vào build scheme.
Resolve và tải các Swift package mà plugin Flutter của bạn phụ thuộc.

Package sinh tự động đó nằm ở ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage. Chữ ephemeral ở đây có ý nghĩa thật — nó được sinh lại, không phải để sửa tay, và không thuộc về version control.

Quan trọng: CocoaPods không biến mất. Flutter tự động fallback về CocoaPods cho bất kỳ dependency nào chưa hỗ trợ SwiftPM, nên một project pha trộn là trạng thái bình thường trong giai đoạn chuyển tiếp, không phải cấu hình sai.

Bật, tắt, và theo từng project

Nếu một phiên bản project trước đó đã tắt, bật lại toàn cục:

flutter config --enable-swift-package-manager

Tắt toàn cục:

flutter config --no-enable-swift-package-manager

Tắt cho riêng một project, trong pubspec.yaml:

flutter:
  config:
    enable-swift-package-manager: false

Công tắc theo project mới là thứ hữu ích. Nếu chỉ đúng một app trong tổ chức phụ thuộc vào một plugin nội bộ chưa migrate, hãy ghim app đó và để mọi thứ còn lại theo mặc định.

Gỡ bỏ hoàn toàn phần tích hợp

Nếu bạn cần rollback sạch — để bisect, hoặc vì build hỏng và bạn muốn một mốc chuẩn:

Tắt SwiftPM bằng một trong hai công tắc trên.
Chạy flutter clean.
Mở Xcode workspace.
Gỡ FlutterGeneratedPluginSwiftPackage khỏi Package Dependencies.
Gỡ nó khỏi Frameworks, Libraries, and Embedded Content.
Xoá pre-action Run Prepare Flutter Framework Script.

Bước 3 đến 6 là những bước hay bị quên, và một phần tích hợp gỡ dở dang sẽ sinh ra lỗi link rất khó hiểu.

Khi migrate tự động thất bại

Tooling đôi khi không vá được project Xcode — scheme tuỳ biến nặng và file project.pbxproj sửa tay là thủ phạm thường gặp. Đường thủ công:

Thêm package dependency. Mở ios/Runner.xcworkspace, vào Package Dependencies, bấm thêm, chọn Add Local…, và chọn ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage. Xác nhận nó gắn vào target Runner và xuất hiện dưới Frameworks, Libraries, and Embedded Content.

Thêm pre-action. Vào Product → Scheme → Edit Scheme, mở Build, bấm Pre-actions, thêm một run script action tên Run Prepare Flutter Framework Script, đặt Provide build settings from thành Runner, và dùng:

"$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" prepare

Sau đó chạy app và xác nhận pre-action có thực thi. Nếu migrate tự động thất bại, hãy báo lỗi kèm project.pbxproj và .xcscheme — đó là dữ liệu đội Flutter cần mà hiếm khi nhận được.

Cái bẫy deployment target

Đây là lỗi thực tế hay gặp nhất, và không hiển nhiên từ thông báo lỗi. Một plugin SwiftPM có thể khai báo phiên bản OS tối thiểu cao hơn app của bạn. Khi đó build sẽ hỏng cho tới khi bạn nâng Minimum Deployments trong Xcode và sinh lại config:

flutter build ios --config-only
flutter build macos --config-only

Flutter 3.47 đã nâng sàn — iOS 13 → 15 và macOS 10.15 → 12 — nên nếu bạn nâng cấp từ SDK cũ, có thể bạn vượt rào này một cách tình cờ.

Khía cạnh	CocoaPods	Swift Package Manager
Manifest dependency	`Podfile` / `Podfile.lock`	`Package.swift` sinh tự động
Toolchain	Ruby gem, cài riêng	Tích hợp sẵn trong Xcode
Điểm tích hợp	`.xcworkspace` từ `pod install`	Package dependency + pre-action của scheme
Trạng thái registry	Chỉ đọc từ 02/12/2026	Đang phát triển tích cực
Mặc định của Flutter	Chỉ dùng làm fallback	Mặc định từ 3.44

Checklist migrate của bạn

Xác nhận bạn đang ở mặc định. Chạy flutter config và kiểm tra enable-swift-package-manager không bị tắt ở đâu, kể cả trong pubspec.yaml.
Build sạch target iOS và macOS và quan sát pre-action có chạy không.
Rà soát danh sách plugin. Với mỗi plugin iOS, kiểm tra repository của nó có kèm Package.swift không. Những cái không có chính là rủi ro tháng 12 của bạn.
Migrate plugin của chính bạn trước — plugin nội bộ là thứ không ai sửa hộ. Theo hướng dẫn cho plugin author và ship Package.swift song song với podspec hiện có.
Mở hoặc upvote issue cho các plugin bên thứ ba chưa migrate mà bạn phụ thuộc, ngay bây giờ thay vì tháng 11.
Nâng deployment target lên iOS 15 / macOS 12 và sinh lại bằng --config-only.
Đừng đưa ios/Flutter/ephemeral/ vào version control.

Kết luận

SwiftPM không phải tính năng bạn cần chủ động áp dụng — gần như chắc chắn bạn đã dùng rồi. Việc bạn cần làm là kiểm kê những plugin chưa chuyển, vì ngày 02/12/2026 sẽ biến câu “để sau tính” thành một lần build hỏng. Phần đầu hệ sinh thái đã xong: 92 trong 100 plugin phổ biến nhất đã chuyển. Bỏ một giờ cho cái đuôi — các plugin nội bộ và ba package ít tên tuổi không ai ngó từ 2024 — và cuộc chuyển đổi này chẳng tốn của bạn gì cả.