No space left on device

#问题描述

在 iOS 端导入大视频文件（5GB+）时，ios设备存储空间设显示有充足的存储空间（如 19GB），但在复制过程中仍然会报错：

❌ 写入失败: No space left on device
💾 当前可用空间: 17.19 GB  // 明明还有空间，为什么失败？

具体表现：

视频复制到约 1.9-2GB 时失败
系统显示剩余空间充足（17-19GB）
错误信息："No space left on device"

#根本原因

经过深入分析，发现问题由两个因素共同导致：

#因素一：iOS 卷宗（Volume）分离机制

发现过程：

在 iPhone 17 上复现此问题时，导致存储空间极度紧张，最终触发了整个 iOS 文件系统崩溃，系统报错：

⚠️ 宗卷 User 空间不足

这个关键错误提示揭示了 iOS 的卷宗分离机制。

技术细节：

iOS 文件系统分为两个独立的卷宗：

卷宗类型	用途	空间管理
系统卷 (System Volume)	存储 iOS 系统文件	系统占用，只读
数据卷 (Data Volume / User Volume)	存储应用数据、用户文件	应用可写

关键点：

iOS "设置 → 通用 → iPhone 存储空间" 显示的可用空间是两个卷宗的总和
但应用数据只能写入数据卷
如果数据卷空间不足，即使系统卷有空间，应用也无法写入

示例：

设备总剩余空间: 19 GB
├─ 系统卷剩余: 15 GB (应用无法使用)
└─ 数据卷剩余: 4 GB  (应用实际可用)

导入 5GB 视频 → 失败! (数据卷只有 4GB)

#因素二：iCloud 自动备份机制

发现过程：

基于因素一进行修复后，测试发现仍然报错，且此时数据卷确实有充足空间。于是怀疑是 iOS 系统对 Documents 目录的特殊限制。

AI 建议了几个方案：

Documents 可能有 2-3GB 限制 → 立即否定（用户之前成功导入过 10GB 文件）
使用 tmp 或 Caches 目录 → 不可行（可能导致数据丢失）
对比中发现关键信息：Documents 会自动备份到 iCloud

技术细节：

iOS Documents 目录的特性：

默认会被 iCloud 自动备份
写入文件时，系统会检查 iCloud 剩余空间
如果文件大小 > iCloud 剩余空间 → 写入失败

实际案例：

数据卷剩余空间: 20 GB ✅
iCloud 剩余空间: 2 GB  ❌

导入 5GB 视频 → 失败!
原因: iCloud 空间不足，无法备份该文件

#解决方案

#方案概述

通过两步优化彻底解决问题：

事前检查数据卷空间 - 避免浪费用户时间
禁用 iCloud 备份 - 移除 iCloud 空间限制

#实现细节

#1. 检查数据卷可用空间

在导入前，使用 Apple 推荐的 API 检查数据卷的实际可用空间：

// 获取数据卷的可用空间（用于重要操作）
let resourceValues = try documentsDirectory.resourceValues(
    forKeys: [.volumeAvailableCapacityForImportantUsageKey]
)

if let availableBytes = resourceValues.volumeAvailableCapacityForImportantUsage {
    let availableGB = Double(availableBytes) / 1024.0 / 1024.0 / 1024.0
    logger.info("💾 数据卷可用空间: \(String(format: "%.2f", availableGB)) GB")

    // 预留 1.5 倍空间（考虑后续处理需要的缓存）
    let requiredSpace = Int64(Double(sourceFileSize) * 1.5)

    if availableBytes < requiredSpace {
        // 提前告知用户空间不足，避免浪费时间
        throw InsufficientStorageError(
            required: requiredSpace,
            available: availableBytes
        )
    }
}

为什么使用 volumeAvailableCapacityForImportantUsageKey？

Apple 提供了三种存储空间查询 API：

API	用途	准确性
`.volumeAvailableCapacityKey`	普通操作	保守估计
`.volumeAvailableCapacityForImportantUsageKey`	重要操作	最准确 ✅
`.volumeAvailableCapacityForOpportunisticUsageKey`	机会性操作	最保守

对于大文件导入这种重要操作，应使用 ForImportantUsage 获取最准确的可用空间。

#2. 禁用 iCloud 备份

将文件标记为"不备份到 iCloud"：

// 方式1: 在文件创建后立即标记（推荐）
let destinationURL = documentsDirectory.appendingPathComponent("import/videos/\(fileName).mp4")

// 创建文件
FileManager.default.createFile(atPath: destinationURL.path, contents: nil, attributes: nil)

// 立即标记不备份
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true
var mutableURL = destinationURL
try mutableURL.setResourceValues(resourceValues)

logger.info("✅ 已标记文件不备份到iCloud")

// 然后再写入大量数据...

关键点：

isExcludedFromBackup = true 告诉系统不要备份该文件
这样写入时就不会检查 iCloud 空间
适合临时导入、可重新获取的大文件

#测试验证

#测试环境

设备：iPhone 17
iOS 版本：iOS 18+
测试文件：5001 MB 视频

#修复前

💾 可用存储空间: 19.09 GB  ← 显示的是系统卷+数据卷总和
📊 源视频文件大小: 5001.30 MB
🔄 开始分块复制文件
📊 已复制 10 MB...
📊 已复制 1910 MB...
📊 已复制 1920 MB...
📊 已复制 1947 MB...
❌ 写入失败: 读取 1048576 字节，但只写入 -1 字节
❌ 写入流错误: No space left on device
💾 当前可用空间: 17.19 GB  ← 仍有空间，但失败了

失败原因：

数据卷实际只有 ~2GB 可用空间
iCloud 剩余空间不足 5GB

#修复后

💾 数据卷可用空间: 20.15 GB  ← 准确检查数据卷
📊 源视频文件大小: 5001.30 MB
✅ 空间充足，可以继续
✅ 已标记文件不备份到iCloud  ← 不受 iCloud 空间限制
🔄 开始分块复制文件
📊 已复制 10 MB...
📊 已复制 1000 MB...
📊 已复制 2000 MB...
📊 已复制 3000 MB...
📊 已复制 4000 MB...
📊 已复制 5000 MB...
✅ 复制完成，总计 5001 MB
✅ 文件验证成功，大小: 5001.30 MB
✅ 导入成功！

#技术总结

#问题本质

iOS 大文件导入失败的两个根本原因：

卷宗分离：设备显示的可用空间 ≠ 应用实际可用空间
iCloud 备份：Documents 文件会触发 iCloud 空间检查

#解决方案核心

精确检查：使用 volumeAvailableCapacityForImportantUsageKey 检查数据卷可用空间
禁用备份：设置 isExcludedFromBackup = true 避免 iCloud 限制

#最佳实践

何时使用 isExcludedFromBackup = true？

✅ 应该使用：

临时导入的大文件
可以重新下载/获取的数据
缓存文件、中间处理文件
用户不需要跨设备同步的数据

❌ 不应使用：

用户创建的文档、照片
无法重新获取的数据
需要跨设备同步的内容

存储目录选择：

目录	备份	清理	适合场景
`Documents/`	默认备份	永久	用户文档（小文件）
`Documents/` + `isExcludedFromBackup`	不备份 ✅	永久	临时导入大文件 ✅
`Library/Caches/`	不备份	空间不足时	可重新下载的缓存
`tmp/`	不备份	应用退出后	临时处理文件