SwiftData迁移深度指南：从入门到填坑上集

时间：2026-07-01 07:04

SwiftData迁移需使用VersionedSchema进行版本控制，定义初始模型和轻量级迁移。引入新版本应在发布后模型变更时进行。轻量级迁移可自动处理增删可选字段，但建议显式定义迁移计划以确保可预测性。复杂迁移如重命名或新增非可选字段则需手动处理。

引子

凌晨两点的办公室，键盘声噼里啪啦。Jason 盯着屏幕，嘴角露出一丝得意的微笑。为了应对 Kevin 明天必须要发布的“次世代运动 App” v1.0 版本，他刚刚提交了最后一行代码。

“等一下，”Chloe 像幽灵一样出现在 Jason 身后，手里端着一杯冰萃咖啡，眼镜片上折射出 Code Review 的冷光，“我看你这 SwiftData 的模型定义，怎么连个版本号都没有？你打算等 Kevin 下个版本又要改需求，用户数据全部原地蒸发的时候，去他办公室表演‘土下座’吗？”

Jason 不以为然地转过椅子：“SwiftData 不是号称 Apple 黑科技、全自动迁移吗？还要啥自行车？”

Chloe 叹了口气，拉过一把人体工学椅坐下：“Naive。SwiftData 迁移（Migrations） 这东西，开发的时候觉得可有可无，直到你发布了更新，而真实用户的真实数据在磁盘上变成一堆乱码时，你才追悔莫及。来，今晚给你补补课。”

在这篇文章及后续的下集里，我们将详细探讨：

如何使用 VersionedSchema 优雅地实现模式版本控制。
何时应当引入新的 Schema 版本。
哪些场景下 SwiftData 可以自动迁移，何时你需要使用 SchemaMigrationPlan 和 MigrationStage 进行手动迁移。
如何处理那些极为复杂的迁移场景（比如需要“桥接”版本的高级操作）。

读完这些内容后，你会对 SwiftData 的迁移规则、能力边界以及局限性形成一个高屋建瓴的认知。更重要的是：你将会知道如何量体裁衣——并非所有的模型改动都需要编写大量迁移代码，但有些改动，少写一行就可能酿成 P0 级事故。

用 VersionedSchema 实现基础版本控制

“首先，”Chloe 指着屏幕上的代码，“所有的模型都应该有‘户口’。在 SwiftData 里，这就是 VersionedSchema。”

哪怕是你还没有发布任何更新的初始模型，也应当包裹在 VersionedSchema 中。

这为你提供了一个稳定的起点。虽然理论上你可以在发布后补加 VersionedSchema，但这就像飞机起飞后再去拧引擎螺丝，风险极高，很容易弄巧成拙。

定义你的初始模型 Schema

如果你以前没有接触过 SwiftData 的版本化模型，初次看到这种嵌套类型可能会觉得画风清奇。但核心思想其实相当简单：

每个 Schema 版本定义自己的一套 @Model 类型，并且这些类型是被“命名空间化”的（例如 ExerciseSchemaV1.Exercise）。
你的业务代码通常只想操作“当前”的模型，而不想在代码里到处写 SchemaV5.Exercise 这样冗长的名称。
此时，typealias（类型别名）就是你的救星，它能让你调用的地方保持清清爽爽，同时在底层又明确指定了你使用的是哪个版本。

这导致了一个很实用的结果：你的代码库里会出现两类“模型”：

版本化模型（Versioned models）： ExerciseSchemaV1.Exercise, ExerciseSchemaV2.Exercise 等。这些是为了让 SwiftData 搞清楚数据的演变历史。
当前模型（Current models）： typealias Exercise = ExerciseSchemaV2.Exercise。这些是为了让你其余 App 代码保持可读性，而不用每次升级 Schema 都重构半个项目。

每个你定义的 Schema 都需要遵循 VersionedSchema 协议，并包含以下两个字段：

versionIdentifier: 这一版 Schema 的语义化版本号。
models: 这一版 Schema 里包含的所有模型类型列表。

一个极简的 V1 → V2 示例

“看着，”Jason 在 Chloe 的“亲切”指导下敲下了代码，“假设我们有一个简单的 Exercise（运动）模型作为 V1。”

到了 V2 版本，Kevin 拍脑门说要加个 notes（备注）字段。这种变更是非常典型的轻量级迁移（Lightweight Migration），因为老数据里没有这个字段，直接给个 nil 也就混过去了。

import SwiftData//  V1 版本定义：这是我们的初始起点
enum ExerciseSchemaV1: VersionedSchema {
  static var versionIdentifier = Schema.Version(1, 0, 0)
  
  // 注册该版本下的所有模型
  static var models: [any PersistentModel.Type] = [Exercise.self]  @Model
  final class Exercise {
    var name: String    init(name: String) {
      self.name = name
    }
  }
}//  V2 版本定义：Kevin 提需求后的产物
enum ExerciseSchemaV2: VersionedSchema {
  static var versionIdentifier = Schema.Version(2, 0, 0)
  
  // 注意：这里的 Exercise 是指下面定义的 V2 版 Exercise
  static var models: [any PersistentModel.Type] = [Exercise.self]  @Model
  final class Exercise {
    var name: String
    var notes: String? //  新增了可选字段，Kevin 满意的笑了    init(name: String, notes: String? = nil) {
      self.name = name
      self.notes = notes
    }
  }
}

在 App 的其余部分，你只需要把当前的 Exercise 指向最新的 V2：

//  这一行是关键，让业务逻辑完全无感
typealias Exercise = ExerciseSchemaV2.Exercise

这样你就可以愉快地写 Exercise(...)，而不是那又臭又长的 ExerciseSchemaV2.Exercise(...) 了。

⏱️ 何时引入新的 VersionedSchema？

Jason 挠挠头：“那我岂不是每改一行代码就要升一个版本？这代码库不得爆炸？”

“别杞人忧天，”Chloe 解释道，“行业经验表明，通常只在 App Store 发版之间有模型变更时，才引入新版本。”

比如，v1.0 的 App 对应 v1.0 的模型。当你在开发 v1.1 的 App 时，如果模型动了，那就引入一个 v2.0 的模型版本。即使你在开发过程中改了八百回模型，对于最终用户来说，只有一次更新。

所以，只有当你已经向用户发布了上一个版本的模型后，再做修改时，才需要引入新的 VersionedSchema。

还有一点要铭记于心：用户的升级路径是千奇百怪的。有的铁粉会跟进每一个版本，有的“钉子户”可能直接从 v1.0 跳到 v2.5。

好消息是，SwiftData 开箱即用地处理了这些复杂的迁移路径，你不需要太操心。但你的模型设计必须能够支持从任何旧版本迁移到任何新版本。

通常，SwiftData 自己就能搞定路径规划，这就引出了下一话题——

自动迁移规则 (Automatic Migration)

“只要你把版本化 Schema 定义对了，SwiftData 大部分时候都能像变魔术一样自动迁移数据。”Chloe 喝了一口咖啡，“但有时候，你可能想帮它一把，提供一个迁移计划（Migration Plan）。”

虽然对于轻量级迁移这不是必须的，但强烈建议你这么做，这样可以优化迁移路径。

SwiftData 眼中的“自动迁移”

SwiftData 能够推断出某些 Schema 的变化，并且不需要你写任何自定义逻辑就能迁移数据库。在迁移计划中，这被称为轻量级阶段（Lightweight Stage）。

这里有个值得注意的细节：SwiftData 可以在完全没有 SchemaMigrationPlan 的情况下执行轻量级迁移。但是！一旦你开始采用版本化 Schema，并且希望在不同发布版本之间拥有可预测、可测试的升级体验，显式地定义迁移阶段是最稳妥的做法。

建议你两种方式（有计划和无计划）都试一下。如果不确定，那就防患于未然，给轻量级迁移也加上计划，反正不亏。

来看看如何定义一个迁移计划，以及如何使用它：

//  定义迁移计划
enum AppMigrationPlan: SchemaMigrationPlan {
  // 注册所有历史版本和当前版本
  static var schemas: [any VersionedSchema.Type] = [
      ExerciseSchemaV1.self, 
      ExerciseSchemaV2.self
  ]
  
  // 定义迁移阶段
  static var stages: [MigrationStage] = [v1ToV2]  //  定义从 V1 到 V2 是“轻量级”迁移
  static let v1ToV2 = MigrationStage.lightweight(
    fromVersion: ExerciseSchemaV1.self,
    toVersion: ExerciseSchemaV2.self
  )
}

在这个计划中，我们告诉了 SwiftData：“嘿，从 V1 变到 V2，你自动处理就行，别紧张。”

最后，在创建 ModelContainer 时，别忘了把这个锦囊妙计塞进去：

// 确保别名指向最新版
typealias Exercise = ExerciseSchemaV2.Exerciselet container = try ModelContainer(
  for: Exercise.self,
  migrationPlan: AppMigrationPlan.self //  注入迁移计划
)