SwiftData模型添加枚举字段遇运行时错误：非可选键路径传nil

问题代码 #

extension Item {
    enum Diet: String, CaseIterable, Codable {
        case herbivorous = "Herbivore"
        case carnivorous = "Carnivore"
        case omnivorous = "Omnivore"
    }
}

@Model
final class Item {
    var name: String = "New item"
    var createdAt: Date = Date()
    var diet: Diet = Diet.herbivorous // <-- 新增字段
    
    init(name: String) {
        self.name = name
    }
}

运行时错误 #

Fatal error: Passed nil for a non-optional keypath \Item.diet

将字段设为可选类型或String类型可解决问题，但需要明确错误原因，同时希望了解SwiftData的调试方法（比如可视化迁移或数据库状态）。

复现步骤 #

• 创建新Xcode项目（macOS、SwiftUI、SwiftData）
• 运行应用，点击加号添加对象后停止应用
• 为Item类添加Diet枚举扩展及diet字段
• 再次运行应用

错误原因 #

1. 自动迁移未填充默认值：首次运行添加的旧Item记录中没有diet字段，新增非可选diet字段后，SwiftData自动迁移不会主动为旧记录填充你定义的默认值（Diet.herbivorous），读取旧记录时该字段返回nil，触发非可选字段不能为nil的致命错误。
2. 枚举类型的迁移限制：尽管枚举实现了Codable和RawRepresentable，但SwiftData自动迁移逻辑对新增的非可选枚举字段处理不完善，不会自动将默认值写入旧记录，仅尝试读取现有数据，旧数据无此字段则返回nil导致崩溃。

调试与解决方法 #

1. 查看数据库状态 #

• Xcode内置工具：运行应用后打开Debug Navigator（快捷键Cmd+7），选择Storage下的SwiftData数据库条目，可直接查看表结构和记录，确认旧记录是否缺少diet字段。
• 第三方SQLite工具：找到应用沙盒中的数据库文件（路径通常为~/Library/Containers/[应用Bundle ID]/Data/Library/Application Support/com.apple.coredata.cloudkit.[...]），用DB Browser for SQLite等工具打开，直接检查数据内容。

2. 调试迁移过程 #

• 开启迁移日志：在Xcode Scheme设置中添加启动参数-com.apple.CoreData.Logging.stderr 1，运行时控制台会输出详细迁移日志，可查看字段处理细节。
• 自定义迁移计划：如果自动迁移无法满足需求，可实现SchemaMigrationPlan主动为旧记录设置默认值，示例代码：

// 定义版本化Schema
enum ItemSchemaV1: VersionedSchema {
    static var versionIdentifier = SchemaVersion(1)
    static var entities: [any Entity.Type] { [Item.self] }
    
    @Model
    final class Item {
        var name: String
        var createdAt: Date
        
        init(name: String) {
            self.name = name
            self.createdAt = Date()
        }
    }
}

enum ItemSchemaV2: VersionedSchema {
    static var versionIdentifier = SchemaVersion(2)
    static var entities: [any Entity.Type] { [Item.self] }
    
    @Model
    final class Item {
        var name: String
        var createdAt: Date
        var diet: Diet = .herbivorous
        
        enum Diet: String, CaseIterable, Codable {
            case herbivorous = "Herbivore"
            case carnivorous = "Carnivore"
            case omnivorous = "Omnivore"
        }
        
        init(name: String) {
            self.name = name
            self.createdAt = Date()
        }
    }
}

// 迁移计划
enum ItemMigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        [ItemSchemaV1.self, ItemSchemaV2.self]
    }
    
    static var stages: [MigrationStage] {
        [migrateV1toV2]
    }
    
    static let migrateV1toV2 = MigrationStage.custom(
        fromVersion: ItemSchemaV1.self,
        toVersion: ItemSchemaV2.self
    ) { context in
        let oldItems = try context.fetch(FetchDescriptor<ItemSchemaV1.Item>())
        for oldItem in oldItems {
            // 手动为旧记录设置默认值
            oldItem.diet = ItemSchemaV2.Item.Diet.herbivorous
        }
        try context.save()
    }
}

初始化ModelContainer时指定迁移计划：

let container = try ModelContainer(
    for: Item.self,
    migrationPlan: ItemMigrationPlan.self
)

3. 临时验证方法 #

删除应用沙盒数据（Xcode中选择Product > Clean Build Folder，再删除应用重新运行），此时无旧数据，新增的非可选枚举字段会正常使用默认值，可验证字段本身逻辑是否正确。

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