SwiftUI中Realm迁移未触发：全局实例与环境配置冲突

问题梳理 #

1. 单例模式下修改schemaVersion后，无报错但迁移块未执行预期逻辑
2. SwiftUI环境中配置Realm时迁移块可正常触发，但需要在视图外持有全局Realm实例
3. 单例与环境配置一致时，环境中的迁移块不再触发；单例未完成初始化时，本该触发迁移的场景也无反应；删除单例的schemaVersion后迁移触发，但单例会因版本不匹配报错

核心原因 #

1. 迁移逻辑范围有限：单例的迁移块仅处理oldVersion <3的场景，当你升级schemaVersion到9或更高时，旧版本数据库的oldVersion不满足条件，导致迁移逻辑不执行，误以为迁移未触发
2. 实例初始化顺序冲突：Realm的迁移仅在首次打开对应数据库实例时触发，若单例先完成初始化并执行迁移，后续SwiftUI环境打开同数据库时版本已匹配，不会再触发迁移；若单例初始化晚于视图加载，且提前设置了全局默认配置，可能导致视图侧的Realm实例无法正确触发迁移
3. 配置不一致或文件复制逻辑问题：单例中复制默认数据库的逻辑可能导致目标路径下的数据库版本与设置的schemaVersion一致，从而跳过迁移

解决方案 #

1. 统一全局配置，完善迁移逻辑 #

确保单例的迁移块覆盖所有版本升级场景，且配置与SwiftUI环境保持一致：

class RealmDatabaseManager {
    static let shared = RealmDatabaseManager()
    let realm: Realm!
    private let containerURL: URL
    
    private init() {
        containerURL = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: ProjectSettings.group)!
        let realmURL = containerURL.appendingPathComponent("default.realm")
        let fileManager = FileManager.default
        
        // 仅首次安装时复制默认数据库（避免覆盖已有新版本数据库）
        if !fileManager.fileExists(atPath: realmURL.path) {
            guard let defaultURL = Realm.Configuration.defaultConfiguration.fileURL else {
                fatalError("默认Realm路径不存在")
            }
            do {
                try fileManager.copyItem(at: defaultURL, to: realmURL)
            } catch {
                print("复制默认数据库失败: \(error)")
            }
        }
        
        // 统一配置，迁移块覆盖所有版本升级
        let config = Realm.Configuration(
            fileURL: realmURL,
            schemaVersion: 32, // 使用最新版本号
            migrationBlock: { migration, oldVersion in
                // 按版本顺序处理迁移逻辑
                if oldVersion < 3 {
                    migration.enumerateObjects(ofType: WordRecordRealm.className()) { oldObject, newObject in
                        // 处理版本<3的迁移操作
                    }
                }
                if oldVersion < 10 {
                    // 处理版本<10的迁移操作
                }
                if oldVersion < 32 {
                    // 处理版本<32的迁移操作
                }
            }
        )
        
        // 设置全局默认配置
        Realm.Configuration.defaultConfiguration = config
        
        do {
            realm = try Realm(configuration: config)
        } catch {
            fatalError("初始化Realm失败: \(error)")
        }
    }
}

2. SwiftUI环境复用单例配置 #

不在环境中重复创建配置，直接使用单例的现成配置，确保一致性：

@main
struct YourApp: App {
    var body: some Scene {
        WindowGroup {
            RouterView()
                .environment(\.realmConfiguration, RealmDatabaseManager.shared.realm.configuration)
        }
    }
}

3. 确保单例优先初始化 #

在App启动时提前初始化单例，保证迁移在视图加载前完成：

@main
struct YourApp: App {
    // 提前初始化单例，触发迁移
    private let _realmManager = RealmDatabaseManager.shared
    
    var body: some Scene {
        WindowGroup {
            RouterView()
                .environment(\.realmConfiguration, RealmDatabaseManager.shared.realm.configuration)
        }
    }
}

4. 排查数据库实际版本 #

若迁移仍未触发，可添加代码检查数据库的实际版本，确认是否与设置的schemaVersion匹配：

// 在单例init中添加版本检查
let realmURL = containerURL.appendingPathComponent("default.realm")
if let metadata = try? FileManager.default.attributesOfItem(atPath: realmURL.path) {
    if let currentVersion = metadata[FileAttributeKey(rawValue: "realm.schemaVersion")] as? Int64 {
        print("当前数据库实际版本: \(currentVersion)")
        print("配置的schemaVersion: 32")
    }
}

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