数据迁移就像保险：平时觉得繁琐，出事时能救命。为了让你轻松掌握这一硬核技能，我们将枯燥的文档改编成了深夜办公室的 Code Review 现场。看盲目乐观的 Jason 如何在技术大拿 Chloe 的"毒舌"指导下，从"删库跑路"的边缘被拉回，一步步掌握 VersionedSchema 与自动迁移的奥义。
🚀 引子
凌晨两点的办公室，键盘声噼里啪啦。Jason 盯着屏幕，嘴角露出一丝得意的微笑。为了应对 Kevin 明天必须要上的"次世代运动 App" v1.0 版本，他刚刚提交了最后一行代码。
"等一下，"Chloe 像幽灵一样出现在 Jason 身后，手里端着一杯冰萃咖啡，眼镜片上折射出 Code Review 的冷光，"我看你这 SwiftData 的模型定义，怎么连个版本号都没有？你打算等 Kevin 下个版本又要改需求，用户数据全部原地蒸发的时候，去他办公室表演'土下座'吗？"
Jason 不以为然地转过椅子："SwiftData 不是号称 Apple 黑科技、全自动迁移吗？还要啥自行车？" @toc
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 也就混过去了。
swift
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：
swift
// 👇 这行代码是关键，让业务逻辑无感
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，并且希望在不同发布版本之间拥有可预测、可测试 的升级体验，显式地定义迁移阶段是最稳妥的做法。
我建议你两种方式（有计划和无计划）都试一下。如果不确定，那就防患于未然，给轻量级迁移也加上计划，反正不亏。
来看看如何定义一个迁移计划，以及如何使用它：
swift
// 👇 定义迁移计划
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 时，别忘了把这个锦囊妙计塞进去：
swift
// 确保别名指向最新版
typealias Exercise = ExerciseSchemaV2.Exercise
let container = try ModelContainer(
for: Exercise.self,
migrationPlan: AppMigrationPlan.self // 👈 注入迁移计划
)Jason 看着屏幕上的代码，若有所思："听起来挺简单啊，那是不是我以后改个字段名、加个非可选属性，它都能自己搞定？"
Chloe 嘴角上扬，露出一丝神秘的微笑："Jason 啊，你还是太年轻。要是 Kevin 让你把 name 改成 title，或者让你加个必须存在的 createdAt 时间戳，你猜 SwiftData 会不会当场死给你看？"
"啊？会炸吗？"
"不仅会炸，还会炸得很惨。这就是我们下集要讲的------什么时候轻量级迁移会失效 ，以及如何手写硬核的迁移逻辑。"
(上集完)
预知后事如何，且看 Jason 如何在 Chloe 的指导下，搞定重命名、默认值回填以及那令人头秃的"桥接版本"迁移。请期待下集！
