mac上docker安装失败若报“failed to install”等错误，大概率是apfs容器未扩容、docker虚拟磁盘（docker.raw）过小或本地快照/缓存占满系统宗卷空间；需依次执行diskutil扩容、调大disk image size至100gb+、清理time machine快照与缓存，必要时用homebrew重装或重置docker。
macos 中 docker 安装失败，若报错含 “failed to install”、“mount failed” 或 “no space left on device”，且你确认硬盘剩余空间充足（比如还有 20gb+），那大概率不是物理磁盘真满了，而是apfs 容器空间未吃满或docker desktop 虚拟磁盘与系统空间分配失衡导致的“假性空间不足”。这两类问题常被混淆，但解决路径明确、互不干扰。
先确认并修复 APFS 容器空间未填满问题
这是最隐蔽的前置原因：Docker Desktop 安装过程需写入 /var、/private/var 等系统路径，而这些路径位于 macOS 的系统宗卷（Macintosh HD）中。如果 APFS 容器本身没占满物理硬盘，系统宗卷就无法获得足够底层空间，哪怕磁盘显示有空闲，安装也会卡在挂载或初始化阶段。
- 打开终端，运行
diskutil apfs list，找到主容器（如Container disk1），查看其 Size 值是否接近你硬盘标称容量（例如 512GB SSD 应显示约 499–500GB） - 若明显偏小（如只有 320GB），说明容器未扩容。再运行
diskutil info disk0（根据实际磁盘编号调整），对比 Total Size 和容器当前 Size，差值即为“不可见空间” - 执行扩容命令：
sudo diskutil apfs resizeContainer diskX 0（X 替换为你的物理磁盘编号，如disk0）。该操作安全、无需重启，完成后容器将自动填满可用物理空间
再检查 Docker Desktop 自身虚拟磁盘是否过小
即使系统容器已满，Docker Desktop 还有一层独立的虚拟磁盘（Docker.raw），默认仅 64GB。安装大镜像（如 m3e-large-api）、启用 Kubernetes 或跑多个服务时极易撑爆它——此时报错 “no space left on device” 实际指向的是这个虚拟盘，而非宿主机硬盘。
- 打开 Docker Desktop → Settings → Resources → Advanced，查看 Disk image size 当前值（常见为 64GB）
- 将其调大（推荐至少 100–120GB），修改后点击 Apply & Restart
- 验证是否生效：终端执行
ls -lh ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw，文件大小应与设置值基本一致
清理干扰性本地快照与缓存
APFS 本地 Time Machine 快照和系统缓存会持续占用 Macintosh HD（系统宗卷）空间。Docker 安装时需临时写入大量日志、证书、配置文件，若系统宗卷剩余空间低于 3–5GB，即使容器已满也可能失败。
- 终端运行
tmutil listlocalsnapshots /，识别非更新类快照（如com.apple.TimeMachine.2026-04-25-...），用sudo tmutil deletelocalsnapshots [快照名]删除旧快照 - 进入 系统设置 → 通用 → 储存空间，等待扫描完成，点击 管理，重点清理“系统文件”下的“缓存文件”“日志文件”
- 确保 Safari、微信等大型 App 已完全退出（Command+Q），再手动清空
~/Library/Caches中对应子目录（不要删整个 Caches 文件夹）
最后验证并重置 Docker Desktop（必要时）
若上述步骤做完仍安装失败，说明 Docker Desktop 自身状态异常（如残留旧进程、权限错乱、vmnetd plist 缺失等），尤其在 M1/M2/M3 芯片 Mac 上较常见。
- 完全退出 Docker Desktop（右键菜单选 Quit）
- 终端执行：
brew install --cask docker（通过 Homebrew 安装最新版，可绕过 dmg 安装器的部分校验缺陷） - 若仍不行，进入 Docker Desktop → Troubleshoot → Reset → Clean / Purge data，该操作会清空所有镜像和容器，但能重置虚拟机环境与权限体系
