iCloud Document 开发与本地沙盒文件操作相比，有一些核心差别和注意点，尤其在文件管理、同步、性能和用户体验上。下面我详细梳理：

1. 存储位置差异

• 沙盒文件

  • 全部文件都存放在应用沙盒的 Documents、Caches、tmp 等目录下。
  • 文件操作完全由应用控制。

• iCloud Document

  • 文件存放在 用户的 iCloud Drive 上，本地可能仅保留缓存副本（根据系统存储策略）。
  • 文件路径通常在 NSUbiquitousContainerURL 对应的 iCloud 容器内。
  • 本地未必始终存在完整文件，可能需要下载。

2. 文件可用性

• 沙盒文件：立即可用，无需网络。

• iCloud Document：

  • 文件可能 只在云端存在，本地需要调用 startDownloadingUbiquitousItem(at:) 下载。
  • 可以通过 NSFileManager 的 isUbiquitousItem(at:) 判断是否在 iCloud。
  • 可以用 evictUbiquitousItem(at:) 清理本地副本，释放磁盘空间。

3. 文件同步

• 沙盒文件：无同步，数据仅在设备本地。

• iCloud Document：

  • 文件会 自动同步到用户其他设备。
  • 需要处理同步冲突，通常通过 NSFileVersion 或 UIDocument 的 handleError(_:userInteractionPermitted:)。
  • 不能假设写入操作立即生效在其他设备上，必须考虑异步同步延迟。

4. 文件操作接口

• 沙盒文件：

  • 使用 FileManager、Data.write(to:)、FileHandle 等标准 API。
  • 没有网络依赖或同步问题。

• iCloud Document：

  • 推荐使用 UIDocument 或 NSFileCoordinator 来操作文件，以支持：

  • 并发访问协调（防止冲突）

  • 异步下载 / 上传

  • NSFileCoordinator + NSFilePresenter 可监控文件变更、同步状态。

5. 性能与大文件处理

• iCloud 可能不保留完整本地副本：

  • 访问大文件时需要检查本地存在性，否则会触发下载。
  • 可以通过 NSMetadataQuery 获取文件状态（本地 / 云端 / 修改日期）。

6. 用户体验注意点

• 必须考虑：

  • 下载进度提示（文件可能尚未下载）
  • 冲突提示或自动合并
  • 本地存储限制和清理（通过 evictUbiquitousItem）
• 避免用户误以为所有文件都即时可用。

7. 总结差异表

💡 核心开发要点总结：

1. 使用 UIDocument 或 NSFileCoordinator 来保证文件协调和同步安全。
2. 对文件的可用性、下载状态和本地占用做判断。
3. 处理同步冲突，尤其在多设备场景。
4. 对大文件和缓存策略做优化，避免占用本地磁盘。
5. 使用 NSMetadataQuery 来查询 iCloud 文件状态。

如果你需要，我可以帮你画一张 iCloud Document 与沙盒文件的操作流程对比图，更直观地看到下载、上传、清理的流程。

你希望我画吗？