小部分用户Core Data迁移进程卡顿问题排查求助

场景回顾 #

SwiftUI + Core Data技术栈，目标iOS15.0+，仅给两个实体新增带默认值的非可选Int64类型字段order，小部分用户更新后出现迁移卡顿。本地无法复现，崩溃日志指向container.loadPersistentStores，且确认loadPersistentStores内部执行异常、completionHandler未触发。已排除主应用与Widget同时迁移、存储空间不足，且给Widget添加了迁移延迟逻辑，但问题依旧。

排查方向 #

模型与迁移配置校验 #

• 确认新旧模型中order字段的默认值配置：检查xcdatamodeld的新旧版本，确保默认值是明确的Int64数值（如0），而非动态表达式或未正确设置的值。iOS15+对默认值的解析存在边缘场景问题，若默认值未被正确序列化到模型文件，会导致迁移异常。
• 验证自动迁移开关：NSPersistentContainer默认启用自动迁移，但如果手动修改了persistentStoreDescriptions的shouldMigrateStoreAutomatically为false，会直接导致迁移失败。可通过打印persistentStoreDescriptions确认配置。
• 检查编译后模型文件完整性：导出用户设备上的momd文件，对比本地编译后的文件，确认是否存在版本冲突、字段类型不匹配等损坏情况。

迁移过程日志与线程检查 #

• 补充loadPersistentStores的详细日志：在completionHandler中记录所有错误信息，同时在调用前后添加时间戳，确认是否是迁移过程中出现死锁或无限等待。
• 开启Core Data底层日志：让用户添加启动参数-com.apple.CoreData.Logging.stderr 1后复现，获取迁移过程的底层日志，排查字段类型转换、默认值赋值阶段的异常。
• 检查线程阻塞：loadPersistentStores默认在后台执行，若代码中存在主线程等待迁移完成的逻辑（如用DispatchSemaphore阻塞），会导致主线程卡顿甚至假死，需确认迁移逻辑完全异步。

用户旧数据异常排查 #

• 检查用户旧存储文件：让用户导出Core Data存储文件，用Core Data Viewer等工具打开，排查是否存在损坏的实体、不符合旧模型约束的数据。自动迁移遇到这类数据时，可能出现无法处理的异常导致卡住。
• 确认字段类型兼容性：排查旧模型中是否存在同名的其他类型字段，或用户设备上的存储是否存在历史遗留的字段类型不匹配问题。

修复建议 #

1. 替换自动迁移为手动轻量迁移 #

针对仅添加带默认值字段的场景，手动实现轻量迁移，避免自动迁移的不确定性：

// 获取新旧模型路径
guard let oldModelURL = Bundle.main.url(forResource: "YourModel_V1", withExtension: "mom"),
      let newModelURL = Bundle.main.url(forResource: "YourModel_V2", withExtension: "mom"),
      let oldModel = NSManagedObjectModel(contentsOf: oldModelURL),
      let newModel = NSManagedObjectModel(contentsOf: newModelURL),
      let mappingModel = NSMappingModel(from: [Bundle.main], forSourceModel: oldModel, destinationModel: newModel) else {
    // 模型加载失败处理，比如创建新默认存储
    return
}

let container = NSPersistentContainer(name: "YourModel")
let migrationManager = NSMigrationManager(sourceModel: oldModel, destinationModel: newModel)
let oldStoreURL = container.persistentStoreDescriptions.first?.url
let newStoreURL = oldStoreURL?.deletingLastPathComponent().appendingPathComponent("NewModel.sqlite")

do {
    try migrationManager.migrateStore(from: oldStoreURL!,
                                      type: NSSQLiteStoreType,
                                      options: nil,
                                      with: mappingModel,
                                      toDestinationURL: newStoreURL!,
                                      destinationType: NSSQLiteStoreType,
                                      destinationOptions: nil)
    // 迁移成功后切换到新存储
    container.persistentStoreDescriptions.first?.url = newStoreURL
} catch {
    // 迁移失败处理，可尝试回退到旧存储或创建全新存储
}

// 加载存储
container.loadPersistentStores { description, error in
    if let error = error {
        // 处理加载错误
    }
}

2. 优化loadPersistentStores执行逻辑 #

• 异步加载存储，主线程不阻塞：SwiftUI中建议在App启动时异步加载持久化存储，加载完成后再初始化主视图，避免主线程等待导致的卡顿。
• 添加超时机制：用DispatchWorkItem包裹loadPersistentStores调用，设置30秒左右的超时时间，超时后判定迁移失败，提示用户并尝试创建新存储。

3. 新增数据恢复机制 #

• 当检测到loadPersistentStores长时间未回调时，备份旧存储文件，创建新的持久化存储，让用户选择恢复旧数据或使用新存储。
• 提供数据导出功能，方便用户反馈问题时提供数据，同时降低数据丢失风险。

4. iOS15+特殊适配 #

• 针对iOS15.0-15.2版本做特殊处理：该区间版本存在Core Data自动迁移的已知Bug，可通过版本判断强制启用手动迁移。
• 明确Int64默认值类型：将默认值设置为0 as Int64，避免被解析为Int32导致类型不匹配。

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