iOS应用重装后RealmSwift数据库从iCloud恢复故障排查

问题描述 #

我开发了一款基于RealmSwift的iOS应用，已实现手动将数据库备份至iCloud的功能。当前数据库可成功备份到iCloud，应用未卸载时恢复功能正常，但卸载重装应用后，恢复功能完全失效，控制台无任何打印输出。需要解决该问题，使应用重装后仍可正常从iCloud恢复数据库。

当前代码 #

备份至iCloud代码 #

let fileManager = FileManager.default

private func retrieveLocalRealmURL() -> URL {
    let urls = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)
    let documentaryDirectory = urls[0]
    let realmURL = documentaryDirectory.appendingPathComponent("default.realm");
    
    return realmURL
}

private func backupRealmToiCloudDrive() {
    let backgroundQueue = DispatchQueue.global(qos: .background)
    
    backgroundQueue.async {
        guard
            let ubiquityURL = FileManager.default.url(forUbiquityContainerIdentifier: nil)
        else {
            return
        }
            
        let iCloudDriveURL = ubiquityURL.appendingPathComponent("Documents")
        let iCloudRealmURL = iCloudDriveURL.appendingPathComponent("default.realm")
        
        let fileExists = FileManager.default.fileExists(atPath: iCloudDriveURL.path, isDirectory: nil)
        
        func copy() {
            let localRealmURL = self.retrieveLocalRealmURL()
            
            do {
                try FileManager.default.copyItem(at: localRealmURL, to: iCloudRealmURL)
                
                DispatchQueue.main.async {
                    let alert = UIAlertController(title: "Sicherung erfolgreich", message: "Die Datenbank wurde erfolgreich in iCloud wiederhergestellt.", preferredStyle: .alert)
                    alert.addAction(UIAlertAction(title: "OK", style: .default, handler: nil))
                    self.present(alert, animated: true, completion: nil)
                }
                
                print("Realm File succesfully uploaded to iCloud")
            } catch {
                print(error.localizedDescription)
            }
        }
        
        if fileExists {
            self.deleteExistedFile(iCloudRealmURL)
            copy()
            print("File already existts, deleting old copy")
        } else {
            do {
                try FileManager.default.createDirectory(at: iCloudDriveURL, withIntermediateDirectories: true, attributes: nil)
                copy()
            } catch {
                print(error.localizedDescription)
            }
        }
    }
}

private func deleteExistedFile(_ url: URL) {
    let fileCoordinator = NSFileCoordinator(filePresenter: nil)
    
    fileCoordinator.coordinate(writingItemAt: url, options: .forDeleting, error: nil) { deleteURL in
        do {
            let fileExists = FileManager.default.fileExists(atPath: deleteURL.path, isDirectory: nil)
            
            if fileExists {
                try FileManager.default.removeItem(at: deleteURL)
            }
        } catch {
            print(error.localizedDescription)
        }
    }
}

从iCloud恢复代码 #

private func restoreRealmFromiCloudDrive() {
    let backgroundQueue = DispatchQueue.global(qos: .background)
    
    backgroundQueue.async {
        guard let ubiquityURL = FileManager.default.url(forUbiquityContainerIdentifier: nil) else {
            return
        }
        
        let iCloudDriveURL = ubiquityURL.appendingPathComponent("Documents")
        let iCloudRealmURL = iCloudDriveURL.appendingPathComponent("default.realm")
        
        let fileExists = FileManager.default.fileExists(atPath: iCloudRealmURL.path, isDirectory: nil)
        
        if fileExists {
            let defaultRealmFileURL = Realm.Configuration.defaultConfiguration.fileURL
            let localRealmURL = self.retrieveLocalRealmURL()
            
            let fileCoordinator = NSFileCoordinator(filePresenter: nil)
            
            fileCoordinator.coordinate(writingItemAt: localRealmURL, options: .forReplacing, error: nil) { writeURL in
                do {
                    print("Realm File exists on iCloud")
                    
                    if FileManager.default.fileExists(atPath: defaultRealmFileURL!.path) {
                        try FileManager.default.removeItem(at: defaultRealmFileURL!)
                    }
                    
                    try FileManager.default.copyItem(at: iCloudRealmURL, to: defaultRealmFileURL!)
                    
                    DispatchQueue.main.async {
                        let alert = UIAlertController(title: "Restore Successful", message: "The restore from iCloud Drive was successful", preferredStyle: .alert)
                        alert.addAction(UIAlertAction(title: "OK", style: .default, handler: nil))
                        self.present(alert, animated: true, completion: nil)
                    }
                    
                } catch {
                    print(error.localizedDescription)
                    print("No Realm File on iCloud")
                }
            }
        }
    }
}

问题根源 #

1. iCloud文件未同步到本地：卸载重装后，iCloud Drive中的文件不会自动下载到设备本地，直接调用fileExists(atPath:)会返回false，导致后续逻辑完全跳过。
2. 缺乏错误日志：url(forUbiquityContainerIdentifier: nil)可能因权限未授权、iCloud未开启等原因返回nil，但代码中直接return未输出任何日志，导致无法排查问题。
3. 未主动触发iCloud文件下载：没有调用FileManager的startDownloadingUbiquitousItem(at:)方法主动将iCloud中的文件下载到本地。

修复方案 #

1. 确保iCloud权限配置正确 #

• 在Xcode Capabilities中开启iCloud Drive，勾选Documents，确认Container ID与开发者后台一致。
• 在Info.plist中添加NSiCloudUsageDescription（iOS 10+必填），说明应用使用iCloud的目的。

2. 修改恢复逻辑，添加iCloud文件同步与错误处理 #

以下是修改后的恢复代码，加入了文件下载、完整错误处理和同步等待逻辑：

private func restoreRealmFromiCloudDrive() {
    let backgroundQueue = DispatchQueue.global(qos: .background)
    var coordinatorError: NSError?
    
    backgroundQueue.async {
        // 1. 检查iCloud容器是否可用，添加错误日志
        guard let ubiquityURL = FileManager.default.url(forUbiquityContainerIdentifier: nil) else {
            print("Error: 无法获取iCloud容器URL，可能是iCloud未开启或权限未授权")
            DispatchQueue.main.async {
                self.showAlert(title: "恢复失败", message: "无法连接到iCloud，请检查iCloud设置")
            }
            return
        }
        
        let iCloudDriveURL = ubiquityURL.appendingPathComponent("Documents")
        let iCloudRealmURL = iCloudDriveURL.appendingPathComponent("default.realm")
        
        // 2. 使用NSFileCoordinator协调访问iCloud文件，主动触发下载
        let fileCoordinator = NSFileCoordinator(filePresenter: nil)
        fileCoordinator.coordinate(readingItemAt: iCloudRealmURL, options: .withoutChanges, error: &coordinatorError) { readURL in
            // 检查文件是否存在于iCloud，注意这里用readURL而非原始URL
            guard FileManager.default.fileExists(atPath: readURL.path) else {
                print("Error: iCloud中不存在备份文件")
                DispatchQueue.main.async {
                    self.showAlert(title: "恢复失败", message: "iCloud中未找到备份数据")
                }
                return
            }
            
            // 3. 主动下载iCloud文件到本地
            do {
                try FileManager.default.startDownloadingUbiquitousItem(at: readURL)
                // 等待下载完成（可根据需求替换为NSMetadataQuery监听）
                while FileManager.default.isUbiquitousItemDownloading(at: readURL) {
                    Thread.sleep(forTimeInterval: 0.5)
                }
                print("iCloud备份文件已下载完成")
            } catch {
                print("Error: 下载iCloud文件失败 - \(error.localizedDescription)")
                DispatchQueue.main.async {
                    self.showAlert(title: "恢复失败", message: "下载备份文件出错")
                }
                return
            }
            
            // 4. 执行恢复逻辑
            guard let defaultRealmFileURL = Realm.Configuration.defaultConfiguration.fileURL else {
                print("Error: 无法获取本地Realm文件URL")
                return
            }
            
            let writeCoordinator = NSFileCoordinator(filePresenter: nil)
            writeCoordinator.coordinate(writingItemAt: defaultRealmFileURL, options: .forReplacing, error: &coordinatorError) { writeURL in
                do {
                    // 删除本地现有Realm文件
                    if FileManager.default.fileExists(atPath: writeURL.path) {
                        try FileManager.default.removeItem(at: writeURL)
                    }
                    // 复制下载好的iCloud文件到本地
                    try FileManager.default.copyItem(at: readURL, to: writeURL)
                    
                    DispatchQueue.main.async {
                        self.showAlert(title: "恢复成功", message: "已从iCloud恢复数据库")
                    }
                    print("Realm数据库恢复成功")
                    
                } catch {
                    print("Error: 恢复数据库失败 - \(error.localizedDescription)")
                    DispatchQueue.main.async {
                        self.showAlert(title: "恢复失败", message: "恢复数据库时出错")
                    }
                }
            }
        }
        
        // 处理fileCoordinator的错误
        if let error = coordinatorError {
            print("Error: 协调iCloud文件访问失败 - \(error.localizedDescription)")
            DispatchQueue.main.async {
                self.showAlert(title: "恢复失败", message: "访问iCloud文件出错")
            }
        }
    }
}

// 封装Alert展示方法
private func showAlert(title: String, message: String) {
    let alert = UIAlertController(title: title, message: message, preferredStyle: .alert)
    alert.addAction(UIAlertAction(title: "OK", style: .default))
    present(alert, animated: true)
}

3. 可选优化：使用NSMetadataQuery监听iCloud文件状态 #

如果需要更优雅的同步等待逻辑，可以使用NSMetadataQuery监听iCloud文件的下载状态，避免Thread.sleep的阻塞方式：

private func setupMetadataQuery(for url: URL) {
    let query = NSMetadataQuery()
    query.searchScopes = [NSMetadataQueryUbiquitousDocumentsScope]
    query.predicate = NSPredicate(format: "%K LIKE %@", NSMetadataItemFSNameKey, url.lastPathComponent)
    
    NotificationCenter.default.addObserver(forName: .NSMetadataQueryDidFinishGathering, object: query, queue: .main) { [weak self] _ in
        query.disableUpdates()
        guard let item = query.results.first as? NSMetadataItem else {
            self?.showAlert(title: "恢复失败", message: "未找到iCloud备份")
            return
        }
        if item.value(forAttribute: NSMetadataItemUbiquitousDownloadingStatusKey) as? String == NSMetadataUbiquitousDownloadingStatusCurrent {
            // 文件已下载完成，执行恢复逻辑
            self?.performRestore(from: url)
        } else {
            // 触发下载
            try? FileManager.default.startDownloadingUbiquitousItem(at: url)
        }
    }
    
    NotificationCenter.default.addObserver(forName: .NSMetadataQueryDidUpdate, object: query, queue: .main) { [weak self] _ in
        guard let item = query.results.first as? NSMetadataItem else { return }
        if item.value(forAttribute: NSMetadataItemUbiquitousDownloadingStatusKey) as? String == NSMetadataUbiquitousDownloadingStatusCurrent {
            query.disableUpdates()
            self?.performRestore(from: url)
        }
    }
    
    query.start()
}

// 单独提取恢复逻辑
private func performRestore(from iCloudURL: URL) {
    guard let defaultRealmFileURL = Realm.Configuration.defaultConfiguration.fileURL else {
        print("Error: 无法获取本地Realm文件URL")
        return
    }
    
    let fileCoordinator = NSFileCoordinator(filePresenter: nil)
    var coordinatorError: NSError?
    
    fileCoordinator.coordinate(writingItemAt: defaultRealmFileURL, options: .forReplacing, error: &coordinatorError) { writeURL in
        do {
            if FileManager.default.fileExists(atPath: writeURL.path) {
                try FileManager.default.removeItem(at: writeURL)
            }
            try FileManager.default.copyItem(at: iCloudURL, to: writeURL)
            
            DispatchQueue.main.async {
                self.showAlert(title: "恢复成功", message: "已从iCloud恢复数据库")
            }
            print("Realm数据库恢复成功")
            
        } catch {
            print("Error: 恢复数据库失败 - \(error.localizedDescription)")
            DispatchQueue.main.async {
                self.showAlert(title: "恢复失败", message: "恢复数据库时出错")
            }
        }
    }
    
    if let error = coordinatorError {
        print("Error: 协调本地文件访问失败 - \(error.localizedDescription)")
    }
}

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