SwiftData模型变更后如何正确更新应用避免崩溃？

SwiftData 应用在模型变更后崩溃，核心原因是旧版本的持久化存储与新模型结构不兼容，必须通过模型迁移处理数据兼容问题。以下是具体操作步骤：

1. 为模型添加版本标识 #

每次修改模型（增删属性、调整类型、变更关系等），都需要递增模型的 schema 版本号：

• 在 @Model 宏中指定 schemaVersion 参数，初始版本设为 1，后续每次修改加 1：

  @Model(schemaVersion: 2) // 从版本1升级到2
  final class TodoItem {
      var title: String
      var isCompleted: Bool
      var newOptionalProperty: String? // 新增的可选属性
  
      init(title: String, isCompleted: Bool) {
          self.title = title
          self.isCompleted = isCompleted
      }
  }
  

2. 配置轻量迁移（大多数场景适用） #

轻量迁移是 SwiftData 自动处理简单变更的方式，支持：

• 添加可选属性
• 添加带默认值的必填属性
• 删除属性
• 重命名属性（需配合 @Attribute(originalName:)）
• 将属性改为可选类型（原属性有默认值时）

配置方式：在初始化 ModelContainer 时指定迁移计划：

let schema = Schema([TodoItem.self])
// 定义从版本1到版本2的轻量迁移
let migrationPlan = SchemaMigrationPlan(
    schemas: [schema],
    stages: [.lightweight(fromVersion: 1, toVersion: 2)]
)

do {
    let container = try ModelContainer(
        for: schema,
        migrationPlan: migrationPlan
    )
    // 将container注入环境供应用使用
} catch {
    fatalError("ModelContainer初始化失败: \(error)")
}

如果是重命名属性，需在新属性上标注原名称：

@Model(schemaVersion: 2)
final class TodoItem {
    @Attribute(originalName: "oldTitle") // 原属性名为oldTitle
    var title: String
    // ...其他属性
}

3. 自定义迁移处理复杂变更 #

如果变更无法通过轻量迁移处理（比如修改属性类型且无默认值、复杂关系调整），需要自定义迁移逻辑：

1. 创建旧版本模型的副本（比如对应版本2的 OldTodoItem），用于读取旧存储中的数据
2. 在迁移计划中添加自定义阶段：

let migrationPlan = SchemaMigrationPlan(
    schemas: [schema],
    stages: [
        .custom(
            fromVersion: 2,
            toVersion: 3,
            willMigrate: { context in
                // 迁移前转换旧数据
                let oldItems = try! context.fetch(FetchDescriptor<OldTodoItem>())
                for oldItem in oldItems {
                    // 将旧数据转换为新模型格式
                    let newItem = TodoItem(
                        title: oldItem.title,
                        isCompleted: oldItem.isDone // 映射旧属性到新属性
                    )
                    context.insert(newItem)
                }
            },
            didMigrate: { context in
                // 迁移完成后的验证或清理
                try? context.save()
            }
        )
    ]
)

4. 测试迁移流程 #

必须模拟真实更新场景验证：

• 安装旧版本应用，添加测试数据
• 直接安装新版本应用（不要卸载旧版本）
• 检查数据是否正确迁移，应用无崩溃

常见坑点规避 #

• 忘记递增 schemaVersion：SwiftData 不会触发迁移，直接导致模型不兼容崩溃
• 新增必填属性未设默认值：轻量迁移无法自动填充数据，需为属性添加默认值或改为可选
• 重命名属性未加 originalName：会被识别为新属性，旧数据无法映射到新属性

内容的提问来源于stack exchange，提问作者matyasl