docker构建卡死极大概率因docker.raw磁盘写满，应立即新开终端执行docker system df查看缓存占用，再运行docker builder prune清理buildx缓存，恢复构建；需配置buildkitd-flags设--oci-worker-gc-keep-storage=10gb或迁移docker.raw至大容量磁盘。
Mac上Docker构建镜像时突然卡在某一层、终端无响应、CPU占用飙升却无进度，极大概率是底层虚拟磁盘Docker.raw已写满，系统无法分配新块导致构建进程被内核挂起；此时强行中断可能留下损坏的中间镜像，后续构建会反复失败。
立即释放空间避免构建中断
这一步必须在构建卡死时立刻执行，不关Docker Desktop，不重启终端，直接进终端操作：
1、新开一个终端窗口，输入 docker system df 查看实时占用——重点关注“BUILD CACHE”和“IMAGES”两行的SIZE列，若BUILD CACHE已超40GB，说明缓存膨胀是主因。
2、运行 docker builder prune 清理Buildx构建缓存，该命令专治卡死型构建，它会移除所有未被引用的构建中间产物，且不碰正在运行的构建任务本身。
3、等待命令返回“Total reclaimed space: X.XXGB”，此时原构建终端通常会在10秒内自动恢复进度——因为阻塞的磁盘IO请求终于获得可用空间。
防止下次构建再卡死
Buildx缓存默认无限增长，Mac上尤其危险；必须限制其上限并启用自动清理：
方法一：设置构建器缓存硬上限
编辑 ~/.docker/buildx/config.json（若不存在则新建），填入：
【注意】buildkitd-flags中的10GB是关键阈值，超过此值Buildkit会自动触发GC回收，必须保留单位“GB”且不能写成数字10。
方法二：强制每次构建后清理缓存
在构建命令末尾追加 --no-cache --progress=plain，例如：docker build . --no-cache --progress=plain
这会让Buildkit跳过缓存复用，虽略微拖慢单次构建，但彻底规避缓存膨胀风险。
终极断根：迁移Docker.raw到大容量磁盘
当你的Mac主盘只剩不到30GB可用空间，而Docker.raw已占25GB以上时，仅靠清理只能撑几天；必须把整个虚拟磁盘迁出系统盘：
第一步：确认目标路径有足够空间
运行 df -h /Volumes/ExternalSSD（将ExternalSSD替换为你外接硬盘的实际卷名），确保可用空间≥当前Docker.raw大小的1.5倍。
第二步：停止Docker Desktop→打开Finder→按Command+Shift+G→粘贴路径：~/Library/Containers/com.docker.docker/Data/vms/0/data/
找到 Docker.raw 文件，将其拖拽复制到外接硬盘根目录（如 /Volumes/ExternalSSD/Docker.raw）。
第三步：关闭Docker Desktop→打开终端→执行：defaults write com.docker.docker filesharingDirectories -array-add "/Volumes/ExternalSSD"defaults write com.docker.docker daemon -dict-add data-root "/Volumes/ExternalSSD"
第四步：重新打开Docker Desktop，进入Preferences → Resources → Disk image location，点击右侧文件夹图标，选择你刚复制过去的 Docker.raw 文件位置。
第五步：点击Apply & Restart，Docker Desktop会自动将旧Docker.raw内容迁移至新位置，并在完成后删除原文件。
