SwiftData版本迁移报错：无法使用分段迁移，协调器模型版本未知

核心问题定位 #

错误Code=134504 "Cannot use staged migration with an unknown coordinator model version."本质是SwiftData无法识别迁移计划中指定的某个模型版本，即便清空设备数据仍触发，说明架构版本注册或迁移计划配置存在隐性问题。

分步排查与修复方案 #

1. 检查版本模型的versionIdentifier唯一性 #

确保每个VersionedSchema的versionIdentifier全局唯一，且迁移计划中引用的ID与模型文件完全一致：

// SchemaV1示例，确认versionIdentifier无重复
enum SchemaV1: VersionedSchema {
    static var versionIdentifier: String = "v1"
    static var models: [any PersistentModel.Type] = [Item.self]
}

• 避免使用纯数字ID（如"1"、"2"），建议带前缀（如"v1"、"v2"）降低冲突概率。

2. 验证MigrationPlan的版本链完整性 #

迁移计划必须明确声明所有版本的顺序，且每个版本都正确关联对应的VersionedSchema：

enum AppMigrationPlan: MigrationPlan {
    static var schemas: [any VersionedSchema.Type] = [SchemaV1.self, SchemaV2.self, SchemaV3.self]
    static var stages: [MigrationStage] = [
        MigrationStage.lightweight(fromVersion: SchemaV1.self, toVersion: SchemaV2.self),
        MigrationStage.lightweight(fromVersion: SchemaV2.self, toVersion: SchemaV3.self)
    ]
}

• 禁止遗漏中间版本（如直接从V1跳到V3），确保stages顺序与版本迭代顺序一致。

3. 清理SwiftData缓存与残留 #

即使清空设备数据，Xcode或模拟器的缓存可能仍残留旧模型信息：

• 执行Xcode -> Product -> Clean Build Folder（快捷键Cmd+Shift+K）。
• 删除Derived Data：Xcode -> Settings -> Locations -> Derived Data，打开文件夹后删除全部内容。
• 重置模拟器：Simulator -> Device -> Erase All Content and Settings，重启后再运行。

4. 确认PersistentContainer初始化配置 #

创建ModelContainer时必须指定迁移计划，且以最新的VersionedSchema为入口，禁止混用旧的模型初始化方式：

let container = try ModelContainer(
    for: SchemaV3.self,
    migrationPlan: AppMigrationPlan.self
)

5. 检查自定义迁移实现（若使用） #

如果是自定义迁移，确保迁移类正确继承SchemaMigrationPlan，且版本匹配：

class V2ToV3Migration: SchemaMigrationPlan {
    static var sourceVersion: SchemaV2.Type = SchemaV2.self
    static var targetVersion: SchemaV3.Type = SchemaV3.self
    
    static func migrate(context: ModelContext, from schema: SchemaV2, to schema: SchemaV3) throws {
        // 自定义迁移逻辑
    }
}

• 自定义迁移类必须全局可访问，不能嵌套在其他类/枚举中。

6. 开启迁移调试日志 #

在Build Settings -> Other Swift Flags中添加-DSWIFTDATA_MIGRATION_DEBUG，运行后控制台会输出详细迁移日志，可直接定位无法识别的版本。

兜底方案 #

若以上步骤无效，尝试完全重建SwiftData相关文件：

1. 备份当前模型和迁移代码。
2. 删除所有VersionedSchema、MigrationPlan和自定义迁移类。
3. 重新创建V1版本，确认正常运行后，逐步添加V2、V3版本及对应迁移计划，每一步都测试运行。

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