macOS升级卡在“空间不足”或APFS错误，本质是容器未吃满物理盘、系统卷被快照/缓存占满、元数据错位；需三步解决：填满APFS容器、清理系统卷无效占用、恢复模式下依序修复数据卷/系统卷/容器。
macOS 系统升级卡在“空间不足”或报 APFS 容器相关错误（如“无法挂载”“no space left on device”），通常不是硬盘真满了，而是空间没被系统正确识别或分配——容器没吃满物理盘、系统宗卷被快照/缓存撑爆、数据宗卷却空着，或者元数据错位导致空间统计失准。解决不需要重装，重点就三件事：填满容器、平衡宗卷、校准结构。
确认并填满 APFS 容器空间
APFS 容器若没占满整块 SSD，剩余空间就是“隐形”的，系统和更新器都看不见。这是最常被忽略的根源：
- 打开终端，运行 diskutil apfs list，找到主容器（如 Container disk1），记下它的 Size
- 再运行 diskutil info disk0（把 disk0 换成你实际的物理盘号），对比 Total Size 和容器 Size 的差值
- 如果差值大于 5GB，说明有未分配空间。执行：
sudo diskutil apfs resizeContainer diskX 0（diskX 替换为容器所在物理盘，如 disk0）
清理系统宗卷的无效占用
容器扩容后仍报错？大概率是 Macintosh HD（系统宗卷）被本地快照、日志、缓存塞满，而 Docker、Swoole 或更新器写入的路径（如 /var/lib/docker、/Library/Updates）都在这里，APFS 不会自动从空闲的 Macintosh HD - Data 借空间：
- 进 系统设置 → 通用 → 储存空间 → 管理，逐项清理“缓存文件”“日志文件”“旧文件”
- 终端运行 tmutil listlocalsnapshots /，删掉非 com.apple.os.update 开头的快照：
sudo tmutil deletelocalsnapshots com.apple.TimeMachine.2026-06-15-082210 - 确保 Docker Desktop 已完全退出，再清空：
rm -rf ~/Library/Caches/com.docker.docker
rm -rf ~/Library/Containers/com.docker.docker
用恢复模式修复宗卷与容器一致性
长期空间失衡可能让元数据错位，比如快照引用断裂、ACL 权限异常，系统就会误判可用空间。这步不删数据，只重建内部映射：
- 重启 Mac，按住 Command + R 进入恢复模式
- 打开磁盘工具 → 左上角 显示 → 显示所有设备
- 先选中 Macintosh HD - Data（数据宗卷），点“急救”；再选同容器下的 Macintosh HD（系统宗卷），也点“急救”
- 最后选中整个容器（如 Container disk1），再点一次“急救”
做完这三步，容器已满、宗卷压力释放、元数据校准完毕。系统更新、Docker 镜像拉取、Swoole 启动等依赖空间的操作基本都能恢复正常。
