我差点就放弃了，蘑菇视频 iOS 的离线播放问题我终于定位到原因了
做移动端功能时，总有些看似随机的「有时能播、有时不能播」问题会把人逼疯。蘑菇视频的离线播放也遇到过类似状况：用户明明已经下载完成，离线列表里显示有缓存，打开播放却报错或黑屏。经过逐步排查和复现，我把真正的原因和稳妥的解决办法给总结出来，分享给遇到类似问题的你。
先说结论（省时间）：问题不是播放器的 bug，而是我把离线文件放在了系统可能被清理的目录（Caches / tmp），导致文件在某些场景被系统删除或移动；加上没有对下载状态和文件完整性做严密检查，最终出现了“显示已下载但无法播放”的假象。把文件放到更稳妥的位置、设置免备份标记、补充校验和播放前的存在性检查后，问题彻底解决。
我怎么定位到问题的（关键排查流程）
- 复现并记录：在几台机型、不同系统版本上反复复现，记录何时可播、何时不可播。发现「磁盘空间紧张时更易出现不可播」的规律。
- 查看设备文件系统：用 Xcode 的 Devices & Simulators 导出 App Container，检查缓存文件是否存在。果然有时候离线记录指向的文件路径不存在。
- 分析下载与存储逻辑：检查代码，发现下载完成后把文件临时放在 tmp 或 Caches 下，有时只写了一个记录但没有确认最终移动成功。
- 日志与用户反馈：在出错路径加入更详细日志（文件路径、文件大小、md5/hash），发现出错时文件被系统清理或没有写完。
问题背后的技术点（一句话版） iOS 会在系统空间紧张时优先清理 Caches 和 tmp，下次打开时离线列表显示的是“记录”而非真实的文件；同时如果下载只是完成了网络传输，但没有做完整性校验或原子移动，也可能导致文件不完整。
稳妥的解决方案（步骤与代码示例） 1) 存储位置：把离线文件放在 Library/Application Support 或 Documents（推荐 Application Support），而不是 Caches 或 tmp。Application Support 不会被系统随意清理。 2) 设置免 iCloud 备份标记：既不想占 iCloud，还不想被系统误删，可以把文件设置为 excludedFromBackup。 3) 原子移动与校验：下载完成后用 atomic move（先下载到临时文件，再移动到目标路径），并做文件大小或 hash 校验，只有校验通过才标记为“已下载”。 4) 播放前检查：打开播放前确认文件存在且大小正常，若异常则触发重试或提示重新下载。 5) HLS / DRM 特殊处理：若采用 HLS 离线（AVAssetDownloadURLSession）或 DRM，需要遵循相应 API 而非普通文件存储。
Swift 示例（保存并设置免备份）： let fileManager = FileManager.default let appSupport = try fileManager.url(for: .applicationSupportDirectory, in: .userDomainMask, appropriateFor: nil, create: true) let targetURL = appSupport.appendingPathComponent("offline_videos/(videoId).mp4")
// 确保目录存在 try fileManager.createDirectory(at: targetURL.deletingLastPathComponent(), withIntermediateDirectories: true)
// 原子移动（下载到 tmp 后移动） try fileManager.moveItem(at: tempDownloadURL, to: targetURL)
// 设置不备份到 iCloud var resourceValues = URLResourceValues() resourceValues.isExcludedFromBackup = true try targetURL.setResourceValues(resourceValues)
// 播放前检查 if !fileManager.fileExists(atPath: targetURL.path) || (try fileManager.attributesOfItem(atPath: targetURL.path)[.size] as? UInt64 ?? 0) == 0 { // 触发重试或重新下载 }
测试要点（避免复发）
- 在各种磁盘剩余量情况下测试（模拟低磁盘空间）。
- 在系统升级、应用更新或从 TestFlight 安装后再次测试。
- 给用户侧 UI 清晰展示：真正下载完成、正在验证、下载失败等状态，而不是单一“已下载”标识。
- 记录下载与文件操作的日志（必要时上传到服务器，用于回溯）。
补充说明
- 如果使用 HLS 离线下载（AVAssetDownloadURLSession），不要把生成的离线 asset 当作普通文件处理，按 AVFoundation 文档的缓存/加载方式管理。
- 若遇到 DRM（FairPlay）相关问题，离线播放还要额外校验授权和票据。
结语 这个问题当时让我一度想放弃重做离线逻辑，但拆开来一条条排查后发现并不是播放器或系统的神秘 bug，而是工程细节没处理好。把文件放到合适的位置、加上原子移动与完整性校验、并在播放前做存在性检查后，离线播放恢复稳定。希望我的经验能帮你少走几步弯路——离线功能看似简单，但细节决定成败。
