第 8 章：云同步 (CloudKit Integration)

与 iCloud 同步 SwiftData 数据

1. 启用 CloudKit 同步功能

// 在初始化 ModelContainer 时启用 CloudKit
let container = try ModelContainer(
    for: YourModel.self,
    configurations: ModelConfiguration(
        cloudKitDatabase: .automatic // 自动启用私有数据库同步
    )
)

2. 同步机制的核心特点

  • 自动同步：数据变更会自动通过 CloudKit 同步到用户的所有设备
  • 冲突解决：默认采用"最后写入优先"策略
  • 隐私保护：
    • 使用用户的 iCloud 账户
    • 数据默认存储在私有数据库（需用户登录）

3. 配置要求

  • Xcode 配置：
    • 启用 iCloud 能力
    • 勾选 "CloudKit" 服务
  • Entitlements 文件：
    • 添加 com.apple.developer.icloud-services 权限
    • 添加 com.apple.developer.cloudkit 容器 ID

4. 同步状态监听

// 通过 NotificationCenter 监听同步状态
NotificationCenter.default.publisher(for: .ckAccountChanged)
    .sink { _ in
        print("iCloud 账户状态发生变化")
    }

5. 数据同步流程

  1. 本地修改通过 ModelContext 保存
  2. SwiftData 将变更记录到本地存储
  3. CloudKit 后台进程捕获变更
  4. 变更通过 CloudKit 同步到其他设备
  5. 接收设备合并变更到本地存储

6. 同步限制与注意事项

  • 数据类型限制：
    • 支持所有 SwiftData 原生类型
    • 复杂类型需确保实现 Codable
  • 配额限制：
    • 免费账户有存储限制
    • 大文件建议使用 CloudKit 资产
  • 网络要求：
    • 需要互联网连接
    • 同步可能延迟（非实时）

7. 调试技巧

// 启动时添加参数查看同步日志
ProcessInfo.processInfo.environment["OS_ACTIVITY_MODE"] = "disable"

8. 常见问题解决方案

  • 同步延迟：强制触发同步：
    container?.cloudKitContainer.fetchShareParticipant(with: ...)
  • 账户切换：监听 NSUbiquityIdentityDidChange 通知
  • 冲突解决：实现自定义合并策略
@Model
class YourModel {
    var timestamp: Date // 用于冲突检测
    
    func merge(with remote: YourModel) {
        // 自定义合并逻辑
    }
}

提示：首次同步可能需要较长时间，建议在 Wi-Fi 环境下进行初始同步

Last Updated::