Quản Lý Dependencies: CocoaPods, Carthage, và Swift Package Manager

Quản lý dependencies quyết định một dự án iOS có tái lập được trên máy của cả đội hay không. Trong năm 2026, với Xcode 27.2 và Swift 6.4.2, Swift Package Manager (SPM) là lựa chọn mặc định cho dự án mới; CocoaPods chủ yếu còn vai trò bảo trì hoặc tương thích legacy, còn Carthage đã gần như bị khai tử. Chọn đúng công cụ chưa đủ: bạn còn phải khóa phiên bản, kiểm soát dependency bắc cầu và kiểm tra nguồn cung cấp trước mỗi lần cập nhật.

Cập nhật 2026

  • SPM được tích hợp trực tiếp vào Xcode, dùng Package.swift, Package.resolved và hỗ trợ local package, binary target có checksum.
  • CocoaPods vẫn chạy được trong dự án cũ nhưng đang ở chế độ maintenance; đừng chọn nó cho app Swift mới chỉ vì thói quen.
  • Carthage không còn là lựa chọn chiến lược. Nếu dự án vẫn dùng Carthage, kế hoạch thực tế là chuyển sang SPM hoặc phân phối XCFramework.
  • Privacy manifest, required-reason API, license, SBOM và chữ ký của SDK bên thứ ba phải được xem như một phần của dependency review.

Quản lý dependencies trong iOS 2026 nên bắt đầu từ đâu?

Hãy coi dependency graph là một phần của sản phẩm, không phải vài dòng cấu hình phụ. App của bạn phụ thuộc trực tiếp vào một package; package đó lại kéo theo các package khác, resource, binary, build setting và đôi khi cả script. Một thay đổi nhỏ ở nút gốc có thể làm thay đổi toàn bộ đồ thị, kích thước app hoặc hành vi runtime.

Trên Xcode 27.2, Swift 6.4.2, luồng làm việc khuyến nghị là: khai báo dependency bằng SPM, commit manifest và file lock, review diff khi cập nhật, rồi để CI resolve và build từ trạng thái sạch. SPM dùng Swift toolchain nên không cần thêm Ruby gem hay một workspace do công cụ sinh ra. Nếu bạn đang làm quen với Xcode, hãy xem lại cách cài đặt và cấu hình Xcode trước khi điều tra lỗi package.

Swift Package Manager: mặc định cho dự án mới

SPM mô hình hóa một package qua bốn lớp dễ phân biệt. Package là đơn vị repository và manifest; product là thứ package công bố cho package khác dùng; target là đơn vị build chứa source hoặc test; còn dependency là package bên ngoài hoặc package cục bộ mà target cần. Một target có thể dùng nhiều product, nhưng bạn chỉ nên công bố product thật sự cần thiết.

File Package.swift là source of truth cho package. Trong một app Xcode, bạn thường thêm package từ File > Add Package Dependencies, nhưng kết quả vẫn được Xcode ghi vào project và lockfile. Khi tách module theo feature, local package giúp team giảm một app target khổng lồ và đặt ranh giới build rõ ràng.

// File: Packages/PaymentsKit/Package.swift
// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "PaymentsKit",
    platforms: [.iOS(.v17)],
    products: [
        .library(name: "PaymentsKit", targets: ["PaymentsKit"])
    ],
    dependencies: [
        // Local package: repository phải có thư mục ../DesignSystem.
        .package(path: "../DesignSystem"),
        // Các quy tắc thường dùng với package Git:
        // .package(url: "https://git.example.com/telemetry.git", from: "2.1.0"),
        // .package(url: "https://git.example.com/crypto.git", exact: "4.0.2")
    ],
    targets: [
        .target(
            name: "PaymentsKit",
            dependencies: [
                .product(name: "DesignSystem", package: "DesignSystem")
            ],
            resources: [.process("Resources")]
        ),
        .testTarget(
            name: "PaymentsKitTests",
            dependencies: ["PaymentsKit"]
        )
    ]
)

Trong ví dụ, PaymentsKit là package, product library có cùng tên, còn hai target là code chính và test. .package(path:) phù hợp với module cùng monorepo hoặc module đang phát triển song song. Với package Git, from: cho phép các bản tương thích trong một major version theo quy tắc semantic versioning; exact: khóa đúng một phiên bản; bạn cũng có thể dùng upToNextMinor, branch hoặc revision khi có lý do rõ ràng. Branch phù hợp thử nghiệm, không phù hợp release có yêu cầu tái lập.

Nếu target chứa ảnh, JSON, font hoặc file khác, hãy khai báo resources bằng .process hoặc .copy theo cách package cần. SPM tạo resource bundle riêng; đừng giả định resource tự nằm trong main bundle. Đây là một nguyên nhân phổ biến khiến màn hình chạy được trên máy phát triển nhưng thiếu ảnh sau khi archive.

Package.resolved và chính sách pinning

Package.swift mô tả khoảng phiên bản có thể chấp nhận, còn Package.resolved ghi lại phiên bản cụ thể mà Xcode đã resolve, cùng revision và checksum cần thiết. Với app và thư viện sản phẩm, thường nên commit Package.resolved để mọi máy và CI dùng cùng graph. Nếu bạn là tác giả một package dùng như dependency, chính sách có thể khác; hãy thống nhất trong team và ghi rõ thay vì commit lúc có, xóa lúc có.

Đừng pin mù quáng mọi thứ vào revision mà không có quy trình nâng cấp. Mỗi lần update, tạo pull request riêng, đọc release note, xem diff của Package.resolved, chạy unit/UI test và archive thử. Giữ phiên bản trực tiếp trong manifest đủ chặt, nhưng để resolver xử lý dependency bắc cầu theo graph tương thích. Khi một dependency kéo theo phiên bản không mong muốn, hãy sửa constraint ở package trực tiếp hoặc nâng package gốc, không chỉnh tay lockfile để che lỗi.

Binary target, checksum và package private

Với SDK đóng, thời gian build lớn hoặc code không được phân phối, XCFramework thường phù hợp hơn source package. SPM hỗ trợ .binaryTarget từ URL kèm checksum; checksum xác nhận archive đúng với artifact mà bạn đã phát hành, nhưng không thay thế việc xác minh nhà cung cấp. Nếu binary đi kèm privacy manifest, hãy bảo đảm PrivacyInfo.xcprivacy nằm trong bundle đúng cách và chữ ký SDK được kiểm tra trước khi đưa vào app.

Package private có thể đặt trong Git server nội bộ, registry tương thích hoặc monorepo. CI cần credential tối thiểu và phải resolve được từ môi trường sạch; không nhúng token vào URL, script hay Package.resolved. Với private package, hãy lập danh mục owner, license, phạm vi quyền truy cập, supported platforms và quy trình thu hồi khi repository hoặc signing key bị thay đổi.

CocoaPods: maintenance và legacy, không phải mặc định mới

CocoaPods dùng Podfile để mô tả target, sau đó tạo Pods project, cấu hình build setting và thường tạo .xcworkspace. Cách này vẫn hữu ích khi vendor chỉ cung cấp podspec, dự án Objective-C cũ phụ thuộc sâu vào xcconfig, hoặc việc chuyển đổi tạo ra rủi ro lớn hơn lợi ích. Tuy nhiên, mỗi lớp tích hợp tự động là một lớp cần debug; dự án phải mở workspace, không phải chỉ mở xcodeproj.

# File: Podfile (legacy)
platform :ios, '17.0'

target 'ShopApp' do
  # use_frameworks! có thể tạo framework động tùy cấu hình.
  # use_frameworks! :linkage => :static là một lựa chọn khác.
  use_frameworks! :linkage => :static
  pod 'VendorOnlySDK', '~> 3.2'
end

# Sau khi thay đổi Podfile:
# pod install  # lần đầu hoặc khi thêm pod
# pod update VendorOnlySDK  # chỉ cập nhật pod được chỉ định

Điểm cần nhớ là pod install và pod update có ý nghĩa khác nhau. Install tôn trọng lockfile hiện có; update giải lại phiên bản trong phạm vi cho phép và có thể làm thay đổi graph. CocoaPods còn đưa static/dynamic framework và các file .xcconfig vào quyết định build. Khi debug, kiểm tra target đang link gì, header search path nào và workspace có được mở đúng hay không.

Nếu Pod duy nhất còn lại là một vendor SDK không có SPM, giữ CocoaPods có thể là quyết định hợp lý. Ghi rõ lý do trong tài liệu kỹ thuật, khóa phiên bản Ruby/CocoaPods trong CI và đặt kế hoạch thay thế. Đừng thêm một Pod mới chỉ vì nó có hướng dẫn cài đặt ngắn hơn.

Carthage: nhận diện để loại bỏ dần

Carthage từng có ưu điểm là không sửa project, build framework và để bạn tự link. Nhưng trong năm 2026, nó đã effectively dead: không còn là lựa chọn có hoạt động phát triển đủ để đặt vào kiến trúc mới. Các dự án còn Cartfile, script carthage bootstrap hoặc thư mục Carthage/Build nên được coi là legacy cần quản lý rủi ro, không phải một phương án thứ ba ngang hàng với SPM.

Hướng chuyển phổ biến là tìm SPM chính thức của vendor, hoặc nhận XCFramework đã ký và tích hợp trực tiếp. Nếu package chỉ phát hành source Swift, SPM source target thường đơn giản hơn. Nếu SDK lớn, proprietary, có nhiều kiến trúc hoặc cần rút ngắn build, dùng XCFramework làm binary target có checksum; bài về XCFramework, thư viện tĩnh và động giúp bạn phân biệt các dạng đóng gói này.

Migrate từ CocoaPods sang SPM

  1. Lập inventory từ Podfile, Podfile.lock, build phases và code import. Ghi cả resource, script phase, xcconfig, module name, privacy manifest và license, không chỉ tên Pod.
  2. Kiểm tra mỗi vendor có package chính thức, XCFramework hoặc binary release hay không. Đọc supported platforms và yêu cầu linker; đừng dùng một repository không rõ chủ sở hữu chỉ vì tên tương tự.
  3. Thêm một dependency vào SPM trong branch riêng, giữ Pod cũ tạm thời, rồi đổi một target hoặc một module sử dụng sang product mới. Build và test sau từng bước.
  4. Loại bỏ Pod khi không còn target nào import nó; xóa script, search path, xcconfig và workspace dependency liên quan. Commit thay đổi project cùng Package.resolved.
  5. Archive từ máy sạch, kiểm tra app bundle, symbol, resource, privacy manifest và size. Chỉ sau đó mới xóa Ruby/CocoaPods khỏi CI.

Dự án hỗn hợp SPM và CocoaPods không sai tuyệt đối, nhưng phải có ranh giới. Tránh kéo cùng một thư viện qua cả hai manager: hai bản static có thể gây duplicate symbols, hai bản dynamic có thể tạo lỗi embed hoặc load sai. Đặt ownership theo target, kiểm tra linker map và dùng một dependency duy nhất cho mỗi module. Việc đọc các khu vực chính trong giao diện Xcode sẽ giúp bạn lần theo Package Dependencies, Build Phases và Report Navigator khi lỗi xuất hiện.

Resolve, update và kiểm tra trong CI

Xcode có thể resolve qua giao diện, nhưng CI nên có lệnh rõ ràng để log lại hành vi. Chạy resolve khi muốn tải đúng graph từ manifest và lockfile; update khi chủ động nâng phiên bản. Không nên chạy update tự do trong mọi build release, vì cùng một commit source có thể cho kết quả khác sau khi registry thay đổi.

# File: ci/resolve-dependencies.sh
set -euo pipefail

xcodebuild -resolvePackageDependencies \
  -workspace ShopApp.xcworkspace \
  -scheme ShopApp \
  -clonedSourcePackagesDirPath "$PWD/.spm"

# Chỉ chạy trong job nâng dependency có review:
# xcodebuild -resolvePackageDependencies \
#   -project ShopApp.xcodeproj -scheme ShopApp -disableAutomaticPackageResolution

# Với Swift package thuần:
# swift package resolve
# swift package update

Tên tham số phụ thuộc bạn build từ workspace hay project; hãy dùng đúng scheme và đường dẫn thực tế. CI release nên bật chế độ không tự resolve ngoài ý muốn, cache source package theo checksum và fail nếu lockfile thay đổi không được review. Swift 6.4 còn có hỗ trợ sinh SBOM trong SwiftPM; đưa SPDX hoặc CycloneDX vào artifact để biết app chứa package nào, phiên bản nào và license nào.

Bảo mật, license và compliance của dependency

Dependency review không kết thúc ở việc build xanh. Kiểm tra transitive dependencies, commit/release signature nếu vendor cung cấp, checksum của binary, quyền ghi repository và lịch sử phát hành. Một package có thể thu thập dữ liệu, gọi required-reason API hoặc chứa privacy manifest riêng; app vẫn phải khai báo app privacy details và đảm bảo manifest của SDK được đóng gói chính xác.

Tạo SBOM mỗi release và đối chiếu với danh mục license đã được phê duyệt. License của package trực tiếp chưa đủ vì package bắc cầu cũng được phân phối trong app. Với SDK thương mại, lưu thỏa thuận và giới hạn sử dụng bên cạnh version lock. Đặc biệt, không chạy script tải binary tùy ý trong build; source URL, checksum, signing và quyền CI phải được review như code production.

Các bẫy thường gặp

  • Không pin phiên bản: dùng branch hoặc khoảng quá rộng khiến máy dev và CI resolve khác nhau. Fix bằng constraint có chủ ý, lockfile và lịch update định kỳ.
  • Commit sai hoặc xóa Package.resolved: app và library có chính sách khác nhau. Chọn một policy theo loại repository và enforce bằng CI.
  • Duplicate symbols khi trộn manager: cùng module đi qua SPM và Pod. Chọn một nguồn, kiểm tra graph và xóa bản trùng.
  • Resource biến mất: code compile nhưng bundle không có file. Khai báo resource target, gọi đúng bundle của package và test một archive thật.
  • Thiếu privacy manifest hoặc chữ ký SDK: dependency chạy local nhưng không đạt yêu cầu phân phối. Kiểm tra mọi bundle sau archive, không chỉ source package.
  • Tin vào package không rõ nguồn: tên repository, fork hoặc binary mirror có thể đánh lừa. Xác minh owner, release, checksum, license và SBOM trước khi merge.

Bảng quyết định nhanh

Tình huống Lựa chọn Điều kiện kiểm tra
App Swift mới, package source SPM Manifest, lockfile, resource và license
SDK proprietary hoặc build nặng SPM binary target/XCFramework Checksum, architecture, privacy manifest, chữ ký
App cũ, vendor chỉ có Pod CocoaPods Podfile.lock, workspace, static/dynamic, xcconfig
Dự án còn Carthage Lập kế hoạch migrate Thay bằng SPM hoặc XCFramework, bỏ script cũ

Checklist trước khi merge

  • Dependency trực tiếp có owner, license, supported platform và lý do sử dụng.
  • Constraint và Package.resolved hoặc lockfile tương ứng đã được review.
  • Không có cùng một product được kéo bởi hai manager; build sạch không có duplicate symbols.
  • Resource, privacy manifest, required-reason API và chữ ký SDK xuất hiện đúng trong archive.
  • CI resolve từ môi trường sạch, chạy test, tạo SBOM và lưu artifact theo commit.

Trong năm 2027, xu hướng đáng theo dõi là package modular hóa sâu hơn, binary delivery có kiểm chứng tốt hơn và SBOM trở thành bước mặc định trong pipeline. Bạn không cần migrate mọi dự án trong một đêm; hãy bắt đầu từ dependency có rủi ro hoặc chi phí build lớn, đo kết quả rồi mở rộng. Với nền tảng tổng thể, iOS roadmap sẽ đặt quản lý package vào đúng mạch học cùng Xcode, Swift, testing và release.