Carthage: nó là gì, trình quản lý phụ thuộc phi tập trung

Carthage là gì?

Carthage là trình quản lý phụ thuộc với kiến trúc phi tập trung, được tạo ra vào năm 2014 bởi các nhà phát triển từ cộng đồng Swift. Carthage không sử dụng sổ đăng ký thông số kỹ thuật trung tâm — mỗi thư viện được kết nối trực tiếp từ kho Git qua URL hoặc tên GitHub. Carthage tải mã nguồn, xây dựng nó thành framework nhị phân (.xcframework hoặc .framework) và cung cấp cho nhà phát triển một tạo phẩm sẵn sàng để tích hợp thủ công vào dự án Xcode.

Kiến trúc của Carthage bao gồm ba thành phần: công cụ CLI carthage, tệp cấu hình Cartfile và thư mục Carthage/Build/ chứa các framework đã xây dựng. Sự khác biệt chính giữa Carthage và CocoaPods là không có sự sửa đổi tự động của .xcodeproj. Carthage không tạo .xcworkspace, không cấu hình cờ trình biên dịch và không tạo Pods.xcconfig. Nhà phát triển tự thêm framework vào dự án qua Xcode, mang lại toàn quyền kiểm soát quy trình tích hợp.

Carthage sử dụng xây dựng phụ thuộc song song, giúp tăng tốc đáng kể quá trình trên bộ xử lý đa lõi. Mỗi phụ thuộc được xây dựng như một mục tiêu riêng biệt và Carthage tự động giải quyết đồ thị các phụ thuộc bắc cầu, xây dựng chúng theo đúng thứ tự. Theo điểm chuẩn của cộng đồng, Carthage xây dựng 15–20 phụ thuộc trung bình trong 30–60 giây trên Mac hiện đại, nhanh hơn CocoaPods cho các dự án có nhiều thư viện. Carthage hỗ trợ tất cả các nền tảng Apple: iOS, macOS, watchOS và tvOS, và từ phiên bản 0.38+ — xây dựng .xcframework phổ quát để hỗ trợ trình mô phỏng và thiết bị Apple Silicon.

Carthage hoạt động như thế nào

Carthage sao chép kho Git của mỗi phụ thuộc, chuyển sang phiên bản được chỉ định (thẻ, commit hoặc nhánh) và chạy xcodebuild để xây dựng framework. Carthage tự động xác định loại dự án Xcode (framework, dynamic framework, thư viện tĩnh) theo lược đồ xây dựng. Nếu một dự án có nhiều lược đồ, Carthage sử dụng lược đồ mặc định (đầu tiên theo thứ tự bảng chữ cái). Sau khi xây dựng, Carthage sao chép framework đã hoàn thành vào Carthage/Build/ và tạo tệp Cartfile.resolved với khóa phiên bản chính xác. Carthage hỗ trợ lưu cache các framework đã xây dựng — việc xây dựng lại mà không có thay đổi phụ thuộc sẽ được bỏ qua.

Các phụ thuộc bắc cầu trong Carthage được xử lý thông qua Cartfile.resolved: Carthage xây dựng đồ thị của tất cả các phụ thuộc cần thiết và xây dựng chúng theo đúng thứ tự. Nếu hai thư viện phụ thuộc vào cùng một thư viện bên thứ ba, Carthage xây dựng nó một lần và sử dụng cho cả hai. Carthage báo cáo lỗi xây dựng với mục tiêu cụ thể và nguyên nhân — điều này đơn giản hóa việc chẩn đoán sự cố.

Cartfile: cấu trúc, cú pháp và ví dụ

Cartfile là tệp cấu hình với cú pháp giống Ruby (định dạng Cartfile) xác định các phụ thuộc của dự án Carthage. Cartfile nằm ở thư mục gốc của dự án bên cạnh .xcodeproj. Mỗi dòng của Cartfile mô tả một phụ thuộc: nguồn (URL Git, kho GitHub) và phiên bản. Cú pháp hỗ trợ khóa phiên bản thông qua thẻ, commit và nhánh.

# Các phụ thuộc cơ bản Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

Chỉ thị github "Owner/Repo" là dạng viết tắt cho các kho GitHub. Carthage tự động xây dựng URL https://github.com/Owner/Repo.git. Đối với GitLab, Bitbucket và các máy chủ Git khác, URL đầy đủ được sử dụng: git "https://gitlab.com/owner/repo.git". Toán tử phiên bản: ~> 5.9 (bất kỳ phiên bản nào từ 5.9 đến 6.0, loại trừ 6.0), == 8.0.0 (phiên bản chính xác), >= 1.0 (phiên bản tối thiểu). Có thể khóa một commit cụ thể qua github "owner/repo" "abc1234".

Ví dụ hoàn chỉnh về Cartfile

Carthage hỗ trợ nhiều thư mục cho các cấu hình khác nhau: Cartfile (chính), Cartfile.private (cho các phụ thuộc nội bộ không được xuất bản) và Cartfile.resolved (tự động tạo). Các phụ thuộc riêng tư hữu ích cho các thư viện chỉ được sử dụng trong bản dựng phát triển, như framework kiểm thử.

# Cartfile — các phụ thuộc chính
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# Đầy đủ URL cho GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# Nhánh phát triển
github "marmelroy/PhoneNumberKit" "development"

github và git là hai loại nguồn trong Cartfile. Loại đầu tiên dành riêng cho GitHub và tự động tạo URL. Loại thứ hai dành cho bất kỳ kho Git công khai hoặc riêng tư nào có URL đầy đủ. Phiên bản có thể được chỉ định dưới dạng thẻ (== 2.1.1), phạm vi ngữ nghĩa (~> 5.9), tên nhánh ("development") hoặc mã băm commit ("a1b2c3d"). Phạm vi ngữ nghĩa (~>) được khuyến nghị cho các phụ thuộc tuân theo SemVer — điều này bảo vệ khỏi các thay đổi phá vỡ trong quá trình cập nhật.

Cartfile.resolved được tạo tự động sau carthage update. Nó khóa phiên bản chính xác của tất cả các phụ thuộc đã cài đặt, bao gồm cả phụ thuộc bắc cầu. Tệp này nên được lưu trong Git — nếu không có nó, lệnh carthage bootstrap trên máy khác sẽ xây dựng các thư viện theo cùng quy tắc, nhưng phiên bản có thể khác nhau. carthage outdated hiển thị danh sách các phụ thuộc đã lỗi thời có phiên bản mới.

Cài đặt và cấu hình Carthage

Carthage được cài đặt qua Homebrew — trình quản lý gói tiêu chuẩn cho macOS. Các phương pháp thay thế: cài đặt từ trình cài đặt .pkg đã xây dựng từ GitHub hoặc xây dựng từ mã nguồn. Carthage yêu cầu Xcode với Command Line Tools (bao gồm xcodebuild) và trên Apple Silicon Mac — Rosetta 2 cho một số phụ thuộc kế thừa.

# Cài đặt Carthage qua Homebrew
brew install carthage

# Kiểm tra phiên bản
carthage version

# Cài đặt từ .pkg (nếu Homebrew không khả dụng)
# Tải xuống Carthage.pkg từ GitHub Releases và cài đặt thủ công

Sau khi cài đặt Carthage, khởi tạo dự án bắt đầu bằng việc tạo Cartfile trong thư mục gốc của dự án. Carthage không có lệnh init — tệp được tạo thủ công trong trình soạn thảo văn bản. Sau khi điền các phụ thuộc vào Cartfile, nhà phát triển chạy carthage bootstrap (nếu Cartfile.resolved đã tồn tại) hoặc carthage update (cài đặt ban đầu hoặc cập nhật). Carthage sao chép các kho, xây dựng framework và đặt chúng vào Carthage/Build/.

Cập nhật Carthage được thực hiện qua brew upgrade carthage. Phiên bản được kiểm tra bằng carthage version. Phiên bản ổn định mới nhất tính đến giữa năm 2025 là 0.40 với hỗ trợ .xcframework mặc định, xây dựng song song được cải thiện và hỗ trợ đầy đủ Swift 6. Từ phiên bản 0.39, Carthage đã ngừng xây dựng .framework kế thừa mà không có lớp tương thích — nên chỉ định rõ ràng --use-xcframeworks.

# Cập nhật Carthage qua Homebrew
brew upgrade carthage

# Cài đặt phiên bản cụ thể
brew install carthage@0.39

# Cài đặt lại hoàn toàn
brew uninstall carthage && brew install carthage

Lưu ý: Carthage không tạo .xcworkspace và không sửa đổi .xcodeproj. Không giống như CocoaPods, Carthage để lại toàn quyền kiểm soát cấu hình Xcode cho nhà phát triển. Điều này có nghĩa là sau khi cài đặt các phụ thuộc, bạn cần tự thêm framework vào Xcode (xem phần «Tích hợp framework Carthage vào Xcode»). Carthage cũng yêu cầu mỗi phụ thuộc phải chứa dự án Xcode hoặc workspace với mục tiêu framework — nếu không bản dựng sẽ thất bại.

Xây dựng framework: bootstrap và update

Carthage cung cấp ba lệnh chính để làm việc với các phụ thuộc: bootstrap, update và build. carthage bootstrap xây dựng các phụ thuộc từ Cartfile.resolved hiện có — được khuyến nghị cho môi trường CI và các nhà phát triển tham gia dự án. carthage update cập nhật Cartfile.resolved lên phiên bản mới nhất (tôn trọng các ràng buộc của Cartfile) và thực hiện xây dựng. carthage build xây dựng tất cả các phụ thuộc được chỉ định mà không lưu phiên bản.

# Cài đặt ban đầu (cập nhật phiên bản)
carthage update --use-xcframeworks --platform iOS

# Xây dựng lại với phiên bản đã khóa
carthage bootstrap --use-xcframeworks --platform iOS

# Chỉ xây dựng một phụ thuộc
carthage build Alamofire --platform iOS

Cờ --use-xcframeworks hướng dẫn Carthage xây dựng .xcframework phổ quát thay vì .framework kế thừa. Điều này đảm bảo hỗ trợ cả trình mô phỏng và thiết bị thực, cũng như Apple Silicon Mac mà không cần thêm tập lệnh. Cờ --platform iOS giới hạn bản dựng trên một nền tảng iOS duy nhất — điều này tăng tốc đáng kể quá trình, đặc biệt nếu dự án bao gồm các thư viện đa nền tảng.

Carthage hỗ trợ xây dựng song song qua cờ --cache-builds, lưu cache các framework đã xây dựng. Khi xây dựng lại, Carthage kiểm tra mã băm commit Git và nếu mã không thay đổi, sẽ bỏ qua biên dịch. Đối với máy chủ CI, nên lưu cache thư mục Carthage/Build/ và ~/Library/Caches/carthage/. Carthage cũng hỗ trợ --verbose để ghi nhật ký chi tiết và --no-use-binaries để buộc xây dựng từ mã nguồn (nếu nhà phát triển không tin tưởng vào tệp nhị phân được xây dựng sẵn).

Tích hợp framework Carthage vào Xcode

Tích hợp framework Carthage vào Xcode được thực hiện thủ công trong bốn bước. Sau khi chạy carthage update hoặc bootstrap, tất cả các framework đã xây dựng nằm trong Carthage/Build/iOS/ (hoặc nền tảng tương ứng). Nhà phát triển mở dự án Xcode, chọn mục tiêu ứng dụng và thêm framework vào General → Frameworks, Libraries, and Embedded Content. Đối với framework thời gian chạy (thư viện động), cần chọn «Embed & Sign» — nếu không ứng dụng sẽ gặp lỗi khi khởi chạy với thông báo «dyld: Library not loaded».

Carthage đối với thư viện tĩnh đơn giản hơn — chúng không yêu cầu giai đoạn nhúng vì được liên kết trực tiếp vào tệp thực thi của ứng dụng. Tuy nhiên, Carthage mặc định xây dựng framework động (ngoại trừ các thư viện tĩnh được cấu hình rõ ràng). Đối với các dự án mà việc giảm kích thước ứng dụng là quan trọng, nên sử dụng liên kết tĩnh thông qua cài đặt Xcode.

Một bước bổ sung là thêm Input Files trong Build Phase → Run Script. Carthage yêu cầu tập lệnh để loại bỏ các tạo phẩm trình mô phỏng khỏi framework đã xây dựng (strip simulator architectures). Tập lệnh này cần thiết cho các bản dựng App Store:

# Run Script cho App Store (strip simulator architectures)
FRAMEWORKS_DIR="${SRCROOT}/Carthage/Build/iOS"
for framework in "$FRAMEWORKS_DIR"/*.framework; do
  bash "$BUILD_DIR/src/scripts/strip-framework.sh" "$framework"
done

Carthage không yêu cầu sử dụng .xcworkspace — tất cả các phụ thuộc đã được xây dựng thành framework nhị phân. Carthage hoạt động trực tiếp với .xcodeproj, không giống như CocoaPods tạo workspace. Điều này đơn giản hóa việc kiểm soát phiên bản và thiết lập CI, vì các phụ thuộc Carthage không thay đổi cấu hình dự án Xcode. Thay đổi duy nhất là thêm framework vào mục tiêu, được ghi lại trong .pbxproj.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods và Swift Package Manager (SPM) là ba trình quản lý phụ thuộc chính trong phát triển iOS. Carthage nổi bật với cách tiếp cận phi tập trung, CocoaPods cung cấp sổ đăng ký tập trung và SPM là giải pháp tích hợp của Apple. Việc lựa chọn giữa chúng phụ thuộc vào yêu cầu dự án, quy mô nhóm và mức độ tự động hóa mong muốn.

Carthage được chọn cho các dự án cần can thiệp tối thiểu vào cấu hình Xcode và toàn quyền kiểm soát quy trình tích hợp. Carthage lý tưởng cho các thư viện và framework mã nguồn mở nơi tác giả muốn cho phép người dùng tự xây dựng các phụ thuộc. Carthage cũng phổ biến trong cộng đồng nhà phát triển coi trọng triết lý UNIX: mỗi công cụ làm tốt một việc. CocoaPods vẫn là tiêu chuẩn cho các dự án doanh nghiệp với hàng chục phụ thuộc nơi tự động hóa quan trọng. SPM là lựa chọn cho các dự án mới vì nó được tích hợp trong Xcode và được Apple phát triển tích cực.

Di chuyển giữa các trình quản lý yêu cầu các cách tiếp cận khác nhau. Carthage → SPM: xóa framework khỏi Xcode, xóa Cartfile và thêm Package Dependencies qua File → Add Package Dependencies. Carthage → CocoaPods: xóa framework Carthage, tạo Podfile, thêm phụ thuộc và chạy pod init && pod install. Khi di chuyển từ Carthage sang CocoaPods hoặc SPM, nhu cầu cập nhật thủ công các framework biến mất — tất cả các phụ thuộc được cập nhật bằng một lệnh duy nhất. Carthage vẫn phù hợp cho các dự án nơi cần tránh khóa nhà cung cấp và duy trì tính minh bạch của việc xây dựng phụ thuộc.

Các vấn đề thường gặp và giải pháp

Carthage là công cụ ổn định, nhưng các nhà phát triển thỉnh thoảng gặp phải các vấn đề điển hình, đặc biệt khi xây dựng trên máy chủ CI, cập nhật Xcode hoặc thay đổi phiên bản Swift. Hầu hết các vấn đề được giải quyết bằng cách xóa bộ nhớ cache, cấu hình đúng --use-xcframeworks và kiểm tra phiên bản iOS tối thiểu.

Lỗi «The file manager returned an error» — xảy ra khi bộ nhớ cache Carthage bị hỏng hoặc xung đột quyền tệp. Giải pháp: xóa bộ nhớ cache bằng rm -rf ~/Library/Caches/carthage và khởi động lại carthage bootstrap. Xóa thư mục Carthage/ trong dự án và xây dựng lại cũng hữu ích. Trên máy chủ CI, bộ nhớ cache Carthage chỉ nên được cập nhật khi Cartfile.resolved thay đổi.

Lỗi «No such module» — framework không được tìm thấy trong Xcode mặc dù bản dựng Carthage thành công. Giải pháp: kiểm tra đường dẫn framework trong General → Frameworks, Libraries, and Embedded Content. Framework phải nằm trong Carthage/Build/iOS/. Đảm bảo .xcframework được thêm đúng cách (kéo lại). Đối với framework động, kiểm tra Embed & Sign. Nếu lỗi vẫn tiếp diễn, thêm FRAMEWORK_SEARCH_PATHS trong Build Settings.

Lỗi xây dựng do không tương thích Swift — thư viện được xây dựng cho phiên bản Swift khác với dự án. Giải pháp: sử dụng carthage update --no-use-binaries để buộc xây dựng từ mã nguồn với cùng phiên bản Swift. Nếu thư viện không biên dịch được dưới phiên bản hiện tại, sử dụng .xcconfig để chỉ định phiên bản Swift hoặc fork thư viện. Từ Carthage 0.39, --use-xcframeworks tự động bao gồm phiên bản Swift chính xác trong tệp nhị phân.

Vấn đề xây dựng CI — Carthage trên CI yêu cầu cấu hình bộ nhớ cache phù hợp. Giải pháp: lưu cache Carthage/Build/ và ~/Library/Caches/carthage/. Sử dụng carthage bootstrap --use-xcframeworks --platform iOS thay vì update trên CI để tránh thay đổi phiên bản. Hành động Carthage chính thức có sẵn cho GitHub Actions. Cho Jenkins — plugin CarthageBuild. Carthage có thể gặp lỗi trên macOS không có GUI — giải pháp: cài đặt brew install xcode-build-server hoặc thêm cờ -UseModernBuildSystem=NO.