Sử dụng XCFrameworks, Thư viện Tĩnh và Động: Kỹ Thuật Đóng Gói Code Chuyên Nghiệp Trên Lộ Trình iOS Developer

Một thư viện iOS chạy được trên máy của bạn chưa có nghĩa là nó đã sẵn sàng để phân phối. Chỉ cần thiếu slice simulator trên Apple Silicon, nhầm static với dynamic, hoặc bỏ quên resource bundle là CI và người dùng sẽ gặp lỗi trước khi app khởi chạy. Bài viết này cập nhật cách đóng gói Swift/iOS với Xcode 27.2 và Swift 6.4.2, từ Swift Package Manager đến XCFramework.

Cập nhật 2026: chọn đúng lớp đóng gói

  • Swift Package Manager (SPM) là lựa chọn mặc định cho source package trong Xcode. Package có thể chứa source target, resource và test; khi cần giấu mã nguồn hoặc cung cấp binary, package có thể khai báo .binaryTarget.
  • XCFramework là container mô tả nhiều biến thể nền tảng và kiến trúc. Nó không tự quyết định thư viện bên trong là static hay dynamic.
  • Mac Apple Silicon chạy simulator arm64; Intel Mac thường cần x86_64. Thiết bị iPhone/iPad hiện dùng slice arm64. Vì vậy một gói iOS thực tế thường có device arm64 và simulator arm64, có thể thêm x86_64 để hỗ trợ máy Intel.
  • SDK iOS 27.2 là bản ổn định trong Xcode 27.2. Privacy manifest, required-reason API và chữ ký của SDK bên thứ ba vẫn là phần của quy trình phân phối, không phải việc dọn dẹp sau cùng.

Ba khái niệm cần tách biệt

SPM package: giao diện dependency cho source hoặc binary

SPM package là cấu trúc và metadata quanh một dependency, thường có Package.swift. Source package đưa Swift source vào quá trình build của app, nên compiler có thể tối ưu, kiểm tra module và kéo theo resource khai báo trong target. Đây là lựa chọn tốt cho code nội bộ, thư viện mở, hoặc module cần được debug và cập nhật thường xuyên.

Một package cũng có thể chỉ đóng vai trò vỏ phân phối binary. .binaryTarget trỏ tới URL của XCFramework zip hoặc tới một binary local; người dùng package không thấy source. Khi binary nằm ở URL, SPM yêu cầu checksum để phát hiện archive bị thay đổi ngoài ý muốn.

XCFramework: container cho nhiều biến thể

.xcframework chứa các thư mục con như ios-arm64 và ios-arm64_x86_64-simulator, cùng Info.plist mô tả platform, variant và binary tương ứng. Xcode chọn đúng variant theo target build, thay vì bắt bạn đưa tất cả platform vào một fat binary duy nhất.

XCFramework có thể chứa framework động hoặc framework tĩnh. Một static XCFramework đưa code vào executable của target tại link time; một dynamic XCFramework thường được embed vào app và được load lúc chạy. Đừng gọi XCFramework là “thư viện động” theo mặc định: đó là lỗi khái niệm khiến cấu hình Embed & Sign bị chọn sai.

.framework và .a: định dạng bên trong, không phải chiến lược duy nhất

.framework là bundle có thể chứa binary, module, headers và resources. Nó thường được dùng cho dynamic framework, nhưng cũng có thể là static framework. .a là archive các object file của static library; bạn cần headers hoặc module map để Swift/Objective-C import được. Các định dạng này vẫn hữu ích cho target nội bộ hoặc legacy, nhưng một file đơn lẻ không giải quyết bài toán device, simulator và nhiều platform.

Static và dynamic: quyết định link ở đâu

Lựa chọn Điều xảy ra Khi phù hợp
Static library/framework Symbol cần thiết được link vào executable; không có framework bên thứ ba phải load lúc runtime. SDK nhỏ, app/extension dùng chung code nhưng cần deployment đơn giản, hoặc muốn giảm overhead dynamic linking.
Dynamic framework Binary được embed và ký trong app; loader liên kết dependency khi chạy. Module lớn, nhiều target trong cùng app cần ranh giới rõ; chấp nhận cấu hình embed và startup cost.
XCFramework Container chứa một hoặc nhiều variant static/dynamic. Phân phối binary cho nhiều platform và architecture.

Static không có nghĩa là luôn nhỏ hơn: nếu app, extension và test target đều kéo cùng archive, symbol có thể xuất hiện ở nhiều executable. Dynamic cũng không cho phép cập nhật thư viện độc lập sau khi phát hành App Store; binary đã nằm trong app vẫn đi qua quy trình build và review như mọi code khác.

Build device và simulator đúng cách

Để đóng gói binary có thể tái sử dụng, bật BUILD_LIBRARY_FOR_DISTRIBUTION=YES cho Release. Với Swift, setting này tạo module interface ổn định hơn giữa các compiler và thể hiện ý định phân phối module. Nó không biến một API đang thay đổi thành API tương thích vô hạn; bạn vẫn phải quản lý ABI, deployment target và các dependency công khai.

Trong Xcode, hãy archive riêng cho generic iOS device và iOS Simulator. Ví dụ dưới đây giả định scheme tên Payments, workspace đã có target framework và output được đặt ở thư mục build ngoài repository:

set -euo pipefail

xcodebuild archive \\
  -workspace Payments.xcworkspace \\
  -scheme Payments \\
  -destination "generic/platform=iOS" \\
  -archivePath "$PWD/build/Payments-iOS.xcarchive" \\
  SKIP_INSTALL=NO \\
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES

xcodebuild archive \\
  -workspace Payments.xcworkspace \\
  -scheme Payments \\
  -destination "generic/platform=iOS Simulator" \\
  -archivePath "$PWD/build/Payments-Sim.xcarchive" \\
  SKIP_INSTALL=NO \\
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES

Archive device sẽ có framework ở Products/Library/Frameworks. Sau đó gom hai variant bằng lệnh chính thức:

xcodebuild -create-xcframework \\
  -framework "build/Payments-iOS.xcarchive/Products/Library/Frameworks/Payments.framework" \\
  -framework "build/Payments-Sim.xcarchive/Products/Library/Frameworks/Payments.framework" \\
  -output "build/Payments.xcframework"

Nếu target là static library, dùng option -library và truyền headers tương ứng:

xcodebuild -create-xcframework \\
  -library "build/Payments-iOS.xcarchive/Products/usr/local/lib/libPayments.a" \\
  -headers "Sources/Payments/include" \\
  -library "build/Payments-Sim.xcarchive/Products/usr/local/lib/libPayments.a" \\
  -headers "Sources/Payments/include" \\
  -output "build/Payments.xcframework"

Các đường dẫn trong ví dụ là cấu trúc archive thông thường; hãy kiểm tra output thật trước khi đưa vào CI. Không dùng lipo để ghép device iOS với simulator: hai file có thể cùng là arm64 nhưng khác platform. lipo chỉ hữu ích để xem hoặc ghép các slice cùng platform trong tình huống legacy, còn XCFramework là cách tách variant được khuyến nghị.

Kiểm tra architecture, module và resource

Đừng đoán rằng Xcode đã chọn slice đúng. Với framework tĩnh hoặc động, lipo -info cho biết architecture; otool -l giúp xem platform load command và otool -L liệt kê dependency động. Chạy kiểm tra trên từng binary bên trong XCFramework:

find build/Payments.xcframework -type f -perm -111 -print
lipo -info build/Payments.xcframework/ios-arm64/Payments.framework/Payments
otool -l build/Payments.xcframework/ios-arm64_x86_64-simulator/Payments.framework/Payments | grep -A3 LC_BUILD_VERSION
otool -L build/Payments.xcframework/ios-arm64/Payments.framework/Payments

Lỗi “building for iOS Simulator, but linking in object file built for iOS” thường là bạn đưa device binary vào simulator target. Lỗi “missing required module” hoặc “could not build Objective-C module” lại thường liên quan đến module map, public headers hoặc module name. Với .a, đảm bảo headers public được truyền vào -headers, module map nằm đúng vị trí và tên module không chứa ký tự khiến Swift import sai.

Resources không tự xuất hiện chỉ vì nằm cạnh binary. Với SwiftPM source target, khai báo resource trong Package.swift và dùng Bundle.module. Với binary framework, đặt resource vào bundle/module được hỗ trợ và test từ một app consumer; nếu SDK có resource bundle riêng, tài liệu tích hợp phải nói rõ app cần copy nó. Test ảnh, localization, JSON và nib trên cả device lẫn simulator.

Đưa XCFramework vào SPM binaryTarget

Đóng zip đúng cấp thư mục, tính checksum rồi khai báo package. Archive nên chứa Payments.xcframework ở root của zip, không thêm một lớp thư mục ngẫu nhiên khiến SPM không tìm thấy bundle.

ditto -c -k --sequesterRsrc --keepParent \\
  build/Payments.xcframework build/Payments.xcframework.zip
swift package compute-checksum build/Payments.xcframework.zip
// File: Package.swift
// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "PaymentsSDK",
    platforms: [.iOS(.v15)],
    products: [
        .library(name: "PaymentsSDK", targets: ["PaymentsSDK"])
    ],
    targets: [
        .binaryTarget(
            name: "PaymentsSDK",
            url: "https://cdn.example.com/Payments.xcframework.zip",
            checksum: "REPLACE_WITH_SWIFT_PACKAGE_COMPUTE_CHECKSUM"
        )
    ]
)

Trong package thật, URL phải là endpoint HTTPS bạn kiểm soát và checksum phải là giá trị được lệnh tính từ đúng file đã upload. Không sửa checksum để “cho qua” khi download lỗi; hãy tìm archive bị sai hoặc bị thay thế. Binary target local hữu ích cho phát triển nội bộ, nhưng URL target và checksum mới phù hợp với release có thể tái lập.

Privacy manifest, signing và notarization

SDK binary phải mang theo PrivacyInfo.xcprivacy nếu nó dùng required-reason API hoặc có dữ liệu cần khai báo. Manifest phải được đặt trong đúng bundle để Xcode đóng gói và tổng hợp thông tin privacy; chỉ đặt một file ở repository không đủ. Kiểm tra các key như NSPrivacyTracking, NSPrivacyCollectedDataTypes và NSPrivacyAccessedAPITypes theo hành vi thực tế của SDK, không sao chép placeholder của app.

Dynamic framework được embed vào app phải được code sign trong quá trình build. SDK phân phối ngoài app có thể cần chữ ký phù hợp với kênh phân phối; đừng giao một binary mà không xác định ai ký, ký ở bước nào và consumer kiểm tra ra sao. Notarization là quy trình Apple dùng chủ yếu cho phần mềm phân phối ngoài Mac App Store; nó không thay thế code signing hoặc App Store validation cho iOS. Với một SDK đa nền tảng, ghi rõ artifact nào cần notarize và artifact nào chỉ cần ký khi embed.

Những bẫy thường gặp

  • Duplicate symbols: hai XCFramework cùng đóng một dependency tĩnh, hoặc app link cả source package lẫn binary của cùng module. Chọn một nguồn, kiểm tra link map và tránh nhúng dependency vào nhiều lớp.
  • Thiếu module map/public header: Objective-C library có thể link nhưng không import được trong Swift. Khai báo module rõ ràng, chỉ export public header cần thiết và kiểm tra module name.
  • Sai architecture hoặc platform: có arm64 không đồng nghĩa dùng được cho simulator. Device arm64 và simulator arm64 là hai platform variant khác nhau.
  • Mất resource bundle: API trả về ảnh hoặc localization nil dù code compile. Đưa resource vào đúng target, truy cập bằng bundle phù hợp và viết test consumer.
  • ABI/module mismatch: binary build không có module stability hoặc public API lộ type không tương thích. Bật BUILD_LIBRARY_FOR_DISTRIBUTION, pin deployment target và thử import bằng Xcode 27.2 sạch.
  • Bitcode legacy: đừng thêm bitcode vào pipeline mới chỉ vì tutorial cũ nhắc tới nó. Kiểm tra build settings hiện tại thay vì phục hồi một workflow đã lỗi thời.
  • Unsigned binary: app build được trên máy phát hành nhưng fail khi consumer hoặc CI ký lại. Xác định ownership của signing, kiểm tra bằng codesign và không coi archive zip là bằng chứng đã hợp lệ.

SPM package, XCFramework hay library cũ?

Nhu cầu Nên chọn Không nên chọn
Module nội bộ, cần debug và đổi code thường xuyên SPM source target hoặc local package Binary opaque chỉ để tránh tạo package
SDK đóng mã nguồn cho nhiều app iOS SPM package chứa binaryTarget trỏ tới XCFramework Một fat .framework thủ công
Target legacy chỉ cần link tĩnh .a + headers/module map, hoặc static XCFramework Dynamic framework nếu không cần runtime boundary
Nhiều platform/architecture XCFramework với variant rõ ràng Dùng lipo để trộn device và simulator

Quy tắc thực dụng là: source package trước; binaryTarget khi bạn thật sự cần binary; XCFramework là container phát hành cho binary; .a và .framework là lựa chọn link bên trong. Nếu consumer chỉ là một app và bạn sở hữu toàn bộ source, đừng biến một module đơn giản thành pipeline binary khó debug.

Nhìn tới 2027 và checklist trước khi phát hành

Từ tháng 4/2027, upload App Store Connect phải build bằng iOS/iPadOS 27 SDK hoặc mới hơn và target iOS 15 trở lên. Một package có checksum, variant simulator cho Apple Silicon, privacy manifest và pipeline kiểm tra architecture ngay hôm nay sẽ giảm đáng kể công việc khi mốc đó đến.

  1. Chọn source package hay binary package dựa trên nhu cầu bảo trì, không dựa vào tên “framework”.
  2. Build và archive riêng device arm64 cùng simulator arm64; thêm x86_64 nếu còn hỗ trợ Intel Mac.
  3. Kiểm tra lipo, otool, module map, public headers và toàn bộ resources bằng một app consumer.
  4. Bật BUILD_LIBRARY_FOR_DISTRIBUTION=YES, tránh bitcode legacy và ghi rõ deployment target.
  5. Zip đúng cấu trúc, tính checksum bằng SwiftPM, ký dynamic binary ở đúng bước và kiểm tra privacy manifest.
  6. Thử một build sạch trên Xcode 27.2/Swift 6.4.2 trước khi đưa artifact lên CDN hoặc CI.

Để nối các mảnh của lộ trình, bạn có thể xem bài về quản lý dependencies, CI/CD cho iOS, cài đặt và cấu hình Xcode, hoặc roadmap iOS tổng thể.