iOS应用图片未同步至iCloud Drive问题排查请求

我开发的iOS应用支持添加图片，图片名称存储在数据库的imagename字段中，数据库通过CloudKit可在iPhone与iPad间快速同步。本地能正常保存并查看图片，但iPad端虽能获取正确的imagename值，却无法显示图片，疑似图片未同步至iCloud Drive。两台设备均已开启应用的iCloud和iCloud Drive权限，以下是相关代码：

原代码片段 #

saveImage()函数 #

private func saveImage() -> String? {
    guard let image = inputImage,
          let imageData = image.jpegData(compressionQuality: 0.5) else {
        return nil
    }
    
    let timestamp = Date().timeIntervalSince1970
    let imageName = "\(UUID().uuidString)-\(timestamp)"
    
    if let existingImageName = tool?.imagename {
        // Delete the existing image
        if let iCloudDocumentsURL = FileManager.default.url(forUbiquityContainerIdentifier: nil)?.appendingPathComponent("Documents") {
            let existingImagePath = iCloudDocumentsURL.appendingPathComponent(existingImageName)
            try? FileManager.default.removeItem(at: existingImagePath)
        } else {
            let documentsDirectory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
            let existingImagePath = documentsDirectory.appendingPathComponent(existingImageName)
            try? FileManager.default.removeItem(at: existingImagePath)
        }
    }
    
    var imagePath: URL
    if let iCloudDocumentsURL = FileManager.default.url(forUbiquityContainerIdentifier: nil)?.appendingPathComponent("Documents") {
        // iCloud storage is available
        imagePath = iCloudDocumentsURL.appendingPathComponent(imageName)
    } else {
        // iCloud storage is not available, use local storage
        let documentsDirectory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
        imagePath = documentsDirectory.appendingPathComponent(imageName)
    }
    
    do {
        try imageData.write(to: imagePath)
        print("Image saved with name: \(imageName)")
        return imageName
    } catch {
        print("Error saving image: \(error.localizedDescription)")
        return nil
    }
}

loadImage()函数 #

func loadImage() {
    if let inputImage = inputImage {
        // An image has already been selected, so just display it
        self.inputImage = inputImage
    } else if let imageName = tool?.imagename {
        // Check both local and iCloud Documents directories for the image
        let localImagePath = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!.appendingPathComponent(imageName)

        var iCloudImagePath: URL?
        if let iCloudURL = FileManager.default.url(forUbiquityContainerIdentifier: nil) {
            iCloudImagePath = iCloudURL.appendingPathComponent("Documents").appendingPathComponent(imageName)
        }

        if FileManager.default.fileExists(atPath: localImagePath.path) {
            // Image exists in local directory, load it from there
            do {
                let imageData = try Data(contentsOf: localImagePath)
                inputImage = UIImage(data: imageData)
            } catch {
                print("Error loading image from local directory: \(error.localizedDescription)")
                inputImage = nil
            }
        } else if let iCloudImagePath = iCloudImagePath, FileManager.default.fileExists(atPath: iCloudImagePath.path) {
            // Image exists in iCloud Documents directory, load it from there
            do {
                let imageData = try Data(contentsOf: iCloudImagePath)
                inputImage = UIImage(data: imageData)
            } catch {
                print("Error loading image from iCloud Documents directory: \(error.localizedDescription)")
                inputImage = nil
            }
        } else {
            // Image not found in either directory
            inputImage = nil
        }
    } else {
        // No image selected
        inputImage = nil
    }
}

PersistenceController代码 #

struct PersistenceController {
    
    static let shared = PersistenceController()

    static var preview: PersistenceController = {
        let result = PersistenceController(inMemory: true)
        let viewContext = result.container.viewContext
        do {

            try viewContext.save()

        } catch {
            let nsError = error as NSError
            fatalError("Unresolved error \(nsError), \(nsError.userInfo)")
        }
        return result
    }()

    let container: NSPersistentCloudKitContainer

    
    init(inMemory: Bool = false) {
        container = NSPersistentCloudKitContainer(name: "HereIsTheContainerName")
        
        if inMemory {
            container.persistentStoreDescriptions.first!.url = URL(fileURLWithPath: "/dev/null")
        }
        container.loadPersistentStores(completionHandler: { (storeDescription, error) in
            if let error = error as NSError? {
                fatalError("Unresolved error \(error), \(error.userInfo)")
            }
        })
        container.viewContext.automaticallyMergesChangesFromParent = true
        container.viewContext.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
    }
}

问题排查 #

1. iCloud文件同步的异步特性未处理 #

直接调用fileExists(atPath:)判断iCloud文件存在性不可靠——iCloud文件可能处于后台下载状态，本地尚未生成缓存，此时该方法会返回false，导致无法加载图片。同时，图片写入iCloud后未等待同步完成，也未监听同步状态。

2. iCloud目录路径处理不严谨 #

• 未确保iCloud Documents目录存在：如果目录不存在，写入操作可能静默失败，图片并未保存到iCloud。
• 路径拼接未明确指定目录类型，可能导致系统识别路径错误。

3. 旧图片删除逻辑存在漏洞 #

删除旧图片时仅针对当前设备的存储位置（iCloud或本地）进行删除，未同时检查另一种存储路径，可能导致旧图片残留，或跨设备同步时旧图片未被清理。

4. 图片加载顺序不合理 #

优先加载本地图片，若iCloud存在更新后的图片但本地未同步，会导致加载旧图或无法找到图片。

修复方案 #

1. 正确处理iCloud文件的异步下载 #

放弃fileExists(atPath:)判断iCloud文件，改用主动触发下载+监听完成事件的方式：

func loadImage() {
    if let inputImage = inputImage {
        self.inputImage = inputImage
    } else if let imageName = tool?.imagename {
        let localImagePath = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!.appendingPathComponent(imageName)
        var iCloudImagePath: URL?
        
        if let iCloudURL = FileManager.default.url(forUbiquityContainerIdentifier: nil) {
            iCloudImagePath = iCloudURL.appendingPathComponent("Documents", isDirectory: true).appendingPathComponent(imageName)
        }
        
        // 优先处理iCloud图片
        if let iCloudImagePath = iCloudImagePath {
            do {
                // 主动触发iCloud文件下载
                try FileManager.default.startDownloadingUbiquitousItem(at: iCloudImagePath)
                // 监听下载完成通知
                NotificationCenter.default.addObserver(forName: .NSUbiquitousFileDownloadCompleted, object: nil, queue: .main) { [weak self] notification in
                    guard let self = self,
                          let downloadedURL = notification.userInfo?[NSUbiquitousFileURLKey] as? URL,
                          downloadedURL == iCloudImagePath else { return }
                    
                    do {
                        let imageData = try Data(contentsOf: iCloudImagePath)
                        self.inputImage = UIImage(data: imageData)
                    } catch {
                        print("加载iCloud图片失败: \(error.localizedDescription)")
                        self.inputImage = nil
                    }
                    NotificationCenter.default.removeObserver(self, name: .NSUbiquitousFileDownloadCompleted, object: nil)
                }
            } catch {
                print("触发iCloud下载失败: \(error.localizedDescription)")
                // 尝试加载本地缓存的iCloud文件
                if FileManager.default.fileExists(atPath: iCloudImagePath.path) {
                    do {
                        let imageData = try Data(contentsOf: iCloudImagePath)
                        inputImage = UIImage(data: imageData)
                    } catch {
                        print("加载iCloud缓存图片失败: \(error.localizedDescription)")
                        inputImage = nil
                    }
                } else {
                    //  fallback到本地图片
                    if FileManager.default.fileExists(atPath: localImagePath.path) {
                        do {
                            let imageData = try Data(contentsOf: localImagePath)
                            inputImage = UIImage(data: imageData)
                        } catch {
                            print("加载本地图片失败: \(error.localizedDescription)")
                            inputImage = nil
                        }
                    } else {
                        inputImage = nil
                    }
                }
            }
        } else {
            // 无iCloud权限，加载本地图片
            if FileManager.default.fileExists(atPath: localImagePath.path) {
                do {
                    let imageData = try Data(contentsOf: localImagePath)
                    inputImage = UIImage(data: imageData)
                } catch {
                    print("加载本地图片失败: \(error.localizedDescription)")
                    inputImage = nil
                }
            } else {
                inputImage = nil
            }
        }
    } else {
        inputImage = nil
    }
}

2. 确保iCloud目录存在并完善删除逻辑 #

保存图片前先创建iCloud Documents目录（如果不存在），同时删除旧图片时检查本地和iCloud双路径：

private func saveImage() -> String? {
    guard let image = inputImage,
          let imageData = image.jpegData(compressionQuality: 0.5) else {
        return nil
    }
    
    let timestamp = Date().timeIntervalSince1970
    let imageName = "\(UUID().uuidString)-\(timestamp)"
    
    // 删除旧图片：同时检查本地和iCloud路径
    if let existingImageName = tool?.imagename {
        let localPath = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0].appendingPathComponent(existingImageName)
        try? FileManager.default.removeItem(at: localPath)
        
        if let iCloudDocumentsURL = FileManager.default.url(forUbiquityContainerIdentifier: nil)?.appendingPathComponent("Documents", isDirectory: true) {
            let iCloudPath = iCloudDocumentsURL.appendingPathComponent(existingImageName)
            try? FileManager.default.removeItem(at: iCloudPath)
        }
    }
    
    var imagePath: URL
    // 处理iCloud存储
    if let iCloudDocumentsURL = FileManager.default.url(forUbiquityContainerIdentifier: nil)?.appendingPathComponent("Documents", isDirectory: true) {
        do {
            // 创建目录（如果不存在）
            try FileManager.default.createDirectory(at: iCloudDocumentsURL, withIntermediateDirectories: true)
            imagePath = iCloudDocumentsURL.appendingPathComponent(imageName)
        } catch {
            print("创建iCloud目录失败: \(error.localizedDescription)")
            // fallback到本地存储
            let documentsDirectory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
            imagePath = documentsDirectory.appendingPathComponent(imageName)
        }
    } else {
        // fallback到本地存储
        let documentsDirectory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
        imagePath = documentsDirectory.appendingPathComponent(imageName)
    }
    
    do {
        try imageData.write(to: imagePath)
        print("图片保存成功，名称: \(imageName)")
        return imageName
    } catch {
        print("保存图片失败: \(error.localizedDescription)")
        return nil
    }
}

3. 完善PersistenceController的CloudKit监听 #

添加CloudKit同步状态监听，便于排查同步问题：

struct PersistenceController {
    static let shared = PersistenceController()
    static var preview: PersistenceController = {
        let result = PersistenceController(inMemory: true)
        let viewContext = result.container.viewContext
        do {
            try viewContext.save()
        } catch {
            let nsError = error as NSError
            fatalError("Unresolved error \(nsError), \(nsError.userInfo)")
        }
        return result
    }()

    let container: NSPersistentCloudKitContainer

    init(inMemory: Bool = false) {
        container = NSPersistentCloudKitContainer(name: "HereIsTheContainerName")
        
        if inMemory {
            container.persistentStoreDescriptions.first!.url = URL(fileURLWithPath: "/dev/null")
        }
        container.loadPersistentStores(completionHandler: { (storeDescription, error) in
            if let error = error as NSError? {
                fatalError("Unresolved error \(error), \(error.userInfo)")
            }
            // 监听CloudKit同步完成事件
            NotificationCenter.default.addObserver(forName: .NSPersistentCloudKitContainerDidImportUbiquitousContentChanges, object: self.container, queue: .main) { _ in
                print("CloudKit数据同步完成")
            }
            // 监听CloudKit同步开始事件
            NotificationCenter.default.addObserver(forName: .NSPersistentCloudKitContainerWillStartImportUbiquitousContentChanges, object: self.container, queue: .main) { _ in
                print("开始CloudKit数据同步")
            }
        })
        container.viewContext.automaticallyMergesChangesFromParent = true
        container.viewContext.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
    }
}

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