No space left on device

问题描述

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

1
2

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

具体表现：

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

根本原因

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

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

发现过程：

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

1

⚠️ 宗卷 User 空间不足

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

技术细节：

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

关键点：

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

示例：

1
2
3
4
5

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

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

因素二：iCloud 自动备份机制

发现过程：

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

AI 建议了几个方案：

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

技术细节：

iOS Documents 目录的特性：

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

实际案例：

1
2
3
4
5

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

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

解决方案

方案概述

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

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

实现细节

1. 检查数据卷可用空间

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// 获取数据卷的可用空间（用于重要操作）
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：

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

2. 禁用 iCloud 备份

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// 方式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 视频

修复前

1
2
3
4
5
6
7
8
9
10

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

失败原因：

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

修复后

1
2
3
4
5
6
7
8
9
10
11
12
13
14

💾 数据卷可用空间: 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 大文件导入失败的两个根本原因：

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

解决方案核心

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

最佳实践

何时使用 isExcludedFromBackup = true？

✅ 应该使用：

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

❌ 不应使用：

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

存储目录选择：

参考资料

• Apple File System Programming Guide
• URLResourceKey - volumeAvailableCapacityForImportantUsageKey
• URLResourceValues - isExcludedFromBackup
• iOS Data Storage Guidelines