Core Data轻量迁移失败：TestFlight真机报near 'null'语法错误

修复实体显示(null)的核心问题 #

• 检查新模型版本的RepeatedDateCD实体类绑定：打开xcdatamodeld的新模型版本，选中实体，在Data Model Inspector的Class字段确认是否正确关联到你的NSManagedObject子类，拼写必须完全一致。真机环境下类名不匹配会导致Core Data无法识别实体，迁移时标记为(null)，触发SQL语法错误。
• 重新生成NSManagedObject子类：通过Xcode的Editor > Create NSManagedObject Subclass...重新生成对应新模型版本的子类，覆盖旧文件，确保属性和模型完全同步。

确保非可选属性的默认值配置正确 #

• 新增的itemState和notificationSource是非可选Int16类型，必须在新模型中设置默认值（比如0）。模拟器可能会自动填充默认值，但真机TestFlight环境下Core Data严格执行模型规则，缺失默认值会导致迁移时生成包含NULL的SQL语句，触发near "null": syntax error。
• 轻量迁移依赖明确的默认值来填充旧数据中不存在的属性，未设置默认值会直接导致迁移失败。

验证App Group共享存储的配置 #

• 确认主App和Widget的App Group ID完全一致，且都在Signing & Capabilities中开启了App Groups并勾选了对应组。真机权限配置错误会导致Core Data无法正确读取旧版本存储文件，误判实体结构。
• 检查存储路径代码：确保CoreDataStack中获取共享容器的代码正确，示例：

  guard let containerURL = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: "group.your.app.id") else {
      fatalError("Failed to get app group container URL")
  }
  let storeURL = containerURL.appendingPathComponent("YourStore.sqlite")
  

  避免使用错误的路径导致访问到无效的存储文件。

调整迁移选项与日志 #

• 在CoreDataStack中明确设置迁移选项，并开启详细日志：

  let container = NSPersistentContainer(name: "YourModelName")
  let storeDescription = NSPersistentStoreDescription(url: storeURL)
  storeDescription.shouldMigrateStoreAutomatically = true
  storeDescription.shouldInferMappingModelAutomatically = true
  // 开启迁移日志便于排查
  storeDescription.setOption(true as NSNumber, forKey: NSPersistentStoreUbiquitousContentLoggingKey)
  container.persistentStoreDescriptions = [storeDescription]
  

• 解决原地迁移问题：如果错误提示Cannot migrate store in-place，可以尝试设置storeDescription.shouldAddStoreAsynchronously = true，或者手动复制旧存储到临时路径完成迁移后再替换原文件，避免真机文件锁定。

真机调试与预验证 #

• 直接用真机调试：安装旧版本到真机，通过Xcode运行新版本，查看控制台的Core Data迁移日志，定位具体的SQL错误语句。TestFlight的日志有限，真机调试能获取更完整的错误信息。
• 清理测试设备数据：删除App后重启设备，清理App Group缓存，再重新安装旧版本升级测试，避免残留的损坏存储文件干扰迁移。

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