用途:为基于数据库的 iCloud 存储与同步提供 CloudKit 综合参考,适用于结构化数据(带关系的记录)同步,而非简单文件同步(后者应使用 axiom-icloud-drive-ref)。适用 iOS 10.0+(基础),CKSyncEngine 与 SwiftData 集成为 iOS 17.0+。
主要能力:
- SwiftData + CloudKit(推荐,iOS 17+):用 @Model 定义模型,通过 ModelConfiguration(cloudKitDatabase: .private("iCloud.com.example.app")) 配置容器,同步自动进行。限制:仅私有数据库,不支持公共/共享库,控制较少。
- CKSyncEngine(WWDC 2023):用于自定义持久化(SQLite、GRDB、JSON)的云同步,自动管理拉取/上传周期、冲突与账号变更。需实现 CKSyncEngineDelegate,处理 stateUpdate、accountChange、fetchedDatabaseChanges、fetchedRecordZoneChanges、sentRecordZoneChanges 等事件,并通过 nextRecordZoneChangeBatch 提供待发送变更。需序列化保存同步状态。
- 原始 CloudKit API:CKContainer、CKDatabase、CKRecord、CKRecordZone、CKAsset。示例包含保存、获取、查询、更新(先取后改再存以避免 serverRecordChanged)、删除,以及 CKModifyRecordsOperation 批量修改。冲突可用 savePolicy(.ifServerRecordUnchanged、.changedKeys)处理,并从 CKError 的 serverRecord/clientRecord 手动合并。
数据库作用域:私有库仅用户可见,跨设备同步;公共库所有用户可读、写入需认证;共享库用于 CKShare 协作(仅受邀用户)。
其他要点:CKAsset 需文件 URL 而非 Data;订阅支持数据库、查询与区域三种类型,配合静默推送处理变更;CKShare 共享记录需位于自定义区域,用 UICloudSharingController 展示,CKAcceptSharesOperation 接受共享;CloudKit Console(https://icloud.developer.apple.com/dashboard)可配置开发者通知、遥测与日志;需配置 iCloud capability 与 CloudKit 容器 entitlements;增量同步可用 CKServerChangeToken。
限制与说明:本资料为参考技能,具体价格、收费、平台范围等未提供;公共/共享数据库不支持 SwiftData 集成;原始 API 方案复杂度更高,仅在 CKSyncEngine 不适用时选用。