0Pricing
Swift Academy · 课时

轻量级迁移与 CloudKit 同步

迁移架构变更，并使用 NSPersistentCloudKitContainer 启用 CloudKit 同步。

轻量级迁移与 CloudKit 同步 是 CoddyKit 上的免费 Swift Academy 课时。 这是第 4 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Swift Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Swift Academy 课程共包含 4 节课。

为什么需要迁移？

当您更改 Core Data 或 SwiftData 模型（添加、重命名或删除属性）时，必须迁移现有存储。

// Without migration, app crashes on launch:
// "The model used to open the store is incompatible with the one used to create the store"

Core Data 中的轻量级迁移

Core Data 可以自动推断简单的迁移（添加属性、重命名属性和删除属性），无需映射模型。

let desc = NSPersistentStoreDescription(url: storeURL)
desc.shouldMigrateStoreAutomatically = true
desc.shouldInferMappingModelAutomatically = true
container.persistentStoreDescriptions = [desc]

.xcdatamodeld 中的版本历史

在 Xcode 中创建新的模型版本：Editor → Add Model Version。将当前版本设置为新版本。

// In MyModel.xcdatamodeld:
// ├── MyModel.xcdatamodel  (v1 - old)
// └── MyModel 2.xcdatamodel (v2 - current)
// Set current version to v2 in File Inspector

SwiftData 架构版本管理

使用 VersionedSchema 和 SchemaMigrationPlan 管理 SwiftData 模型版本。

enum AppSchemaV1: VersionedSchema {
  static var versionIdentifier = Schema.Version(1,0,0)
  static var models: [any PersistentModel.Type] { [ItemV1.self] }
  @Model final class ItemV1 { var name: String; init(name: String) { self.name = name } }
}

SchemaMigrationPlan

在 SchemaMigrationPlan 中定义版本之间的迁移阶段，引导 SwiftData 完成升级。

enum AppMigrationPlan: SchemaMigrationPlan {
  static var schemas: [any VersionedSchema.Type] { [AppSchemaV1.self, AppSchemaV2.self] }
  static var stages: [MigrationStage] { [migrateV1toV2] }
  static let migrateV1toV2 = MigrationStage.lightweight(fromVersion: AppSchemaV1.self, toVersion: AppSchemaV2.self)
}

自定义迁移阶段

对于复杂迁移（数据转换），请使用带有 willMigrate 和 didMigrate 闭包的 .custom 阶段。

static let migrateV1toV2 = MigrationStage.custom(
  fromVersion: AppSchemaV1.self,
  toVersion: AppSchemaV2.self,
  willMigrate: { context in
    // transform old data
  },
  didMigrate: nil
)

NSPersistentCloudKitContainer

将 NSPersistentContainer 替换为 NSPersistentCloudKitContainer，以启用 CloudKit 同步。

let container = NSPersistentCloudKitContainer(name: "MyModel")
container.loadPersistentStores { _, error in
  if let error { fatalError("\(error)") }
}
container.viewContext.automaticallyMergesChangesFromParent = true

CloudKit 要求

CloudKit 同步需要：已登录的 iCloud 账户、CloudKit 权限，以及在开发者门户中配置的 CloudKit 容器。

// Xcode: Signing & Capabilities → + → iCloud → CloudKit
// Enable "Use CloudKit" in Core Data model inspector

使用 CloudKit 的 SwiftData

传入带有 cloudKitDatabase 的 ModelConfiguration，以在 SwiftData 中启用 CloudKit 同步。

let config = ModelConfiguration(
  schema: schema,
  cloudKitDatabase: .automatic
)
let container = try ModelContainer(for: schema, configurations: config)

处理同步冲突

Core Data CloudKit 使用“最后写入者胜出”策略解决冲突。请设计模型，尽量减少并发写入竞争。

// Best practice: keep models granular
// One attribute per write concern
// Avoid large blobs that frequently change

测试迁移

发布前，请在生产存储的副本上测试迁移，以便在影响用户之前发现问题。

// Copy production store to a temp location
// Load it with the new container and verify objects are intact

迁移监控

监听 Core Data 迁移通知，以便在耗时较长的迁移期间显示进度界面。

NotificationCenter.default.addObserver(
  forName: .NSPersistentStoreCoordinatorStoresWillChange,
  object: container.persistentStoreCoordinator,
  queue: .main
) { _ in showMigrationProgress() }

快速检查

哪个 NSPersistentContainer 子类可以启用自动 CloudKit 同步？

课程回顾

对于简单更改，使用 shouldMigrateStoreAutomatically 启用轻量级迁移。对于 SwiftData，使用 VersionedSchema + SchemaMigrationPlan。将容器替换为 NSPersistentCloudKitContainer，或使用 ModelConfiguration(cloudKitDatabase: .automatic)，即可启用 CloudKit 同步。

常见问题解答

「轻量级迁移与 CloudKit 同步」课时是免费的吗？

是的 — 「轻量级迁移与 CloudKit 同步」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Swift Academy 课程的其余内容，请升级到 CoddyKit PRO。 Swift Academy 课程共包含 4 节课。

「轻量级迁移与 CloudKit 同步」这节课中我会学到什么？

迁移架构变更，并使用 NSPersistentCloudKitContainer 启用 CloudKit 同步。 你通过在浏览器中直接运行的动手代码来练习 Swift Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Swift Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Swift Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 4 节课，共 4 节。

「轻量级迁移与 CloudKit 同步」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Swift Academy 课中编写并运行代码吗？

能。每节 Swift Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. Core Data 堆栈：设置 NSPersistentContainer
  2. SwiftData @Model 与 ModelContext
  3. 关系与 FetchDescriptor
  4. 轻量级迁移与 CloudKit 同步
← 返回 Swift Academy