遇到 Docker Compose 构建报错"No space left on device"，通常是宿主机磁盘空间不足或 Docker 内部缓存堆积导致的，建议优先检查宿主机磁盘使用率并清理 Docker 构建缓存。

命令速用版

以下是快速排查和清理的常用命令，可按顺序执行：

# 1. 检查宿主机磁盘空间
df -h

# 2. 检查 inode 使用情况（防止小文件耗尽）
df -i

# 3. 查看 Docker 磁盘使用概况
docker system df

# 4. 清理 Docker 构建缓存和未使用资源（谨慎使用）
docker system prune -a

# 5. 专门清理 BuildKit 构建缓存
docker builder prune

# 6. 清理 Composer 全局缓存（若构建涉及 PHP）
composer clear-cache
rm -rf ~/.composer/cache/vcs/*

为什么会这样

"No space left on device"错误通常由两种情况引起：一是磁盘物理空间确实已满，二是磁盘 inode 耗尽。Docker 构建过程中会生成大量中间镜像层和缓存文件，尤其是使用 BuildKit 时，构建缓存可能占用大量空间。此外，如果构建过程涉及 Composer 安装依赖，其缓存目录（~/.composer/cache）包含数万个小文件，容易在 APFS 或某些 Linux 配置下触发 inode 耗尽，即使磁盘空间显示充足也会报错。

分步处理

1. 检查宿主机磁盘状态

首先确认是磁盘块不足还是 inode 不足。运行 df -h 查看可用空间，若 Use% 接近 100% 需清理大文件。同时运行 df -i 查看 inode 使用率，若 IUse% 接近 100%，即使磁盘有空余也无法写入新文件。

2. 清理 Docker 资源

使用 docker system df 查看 Docker 内部资源占用。若构建缓存或悬挂镜像过多，可执行 docker system prune -a 清理未使用的容器、网络和镜像。注意该命令会删除所有停止的容器和未使用的镜像，使用前请确认无重要数据。

3. 清理构建缓存

针对构建过程中的空间不足，可专门清理 BuildKit 缓存：docker builder prune。若构建涉及 PHP 项目，Composer 缓存也可能占满空间，可手动删除 ~/.composer/cache/vcs/ 目录或运行 composer clear-cache。

4. 清理系统日志和临时文件

若宿主机空间紧张，可检查 /var/log 目录下的日志文件，使用 truncate 命令清空特定日志或删除旧日志。同时清理 /tmp 目录下的临时文件也能释放部分空间。

怎么验证是否生效

执行清理操作后，再次运行 df -h 和 df -i 确认可用空间和 inode 数量已回升。随后重新运行 docker compose build 命令，若构建顺利完成且无报错，则说明问题已解决。若仍报错，需检查 Docker 守护进程存储目录（通常 /var/lib/docker）所在分区是否独立且空间充足。

常见坑

1. inode 耗尽误判：很多用户只看了 df -h 发现还有空间就以为没问题，实际是 df -i 显示 inode 已满，尤其是缓存目录含大量小文件时。

2. 误删重要镜像：使用 docker system prune -a 时会删除所有未使用镜像，包括可能需要的基准镜像，建议先列出镜像确认后再清理。

3. Composer 缓存路径：Composer 缓存默认在 ~/.composer/cache，若该目录所在分区空间紧张，清理后很快又会被填满，建议配置镜像源或禁用 vcs 缓存。

4. Docker 存储目录迁移：若根分区空间长期不足，可考虑将 Docker 存储目录迁移至更大容量的分区，但需停止 Docker 服务并配置 daemon.json。

参考来源

• 【Docker】docker build 构建时遇到的 "no space left on device" 错误 - warm3snow - 博客园
• 如何快速定位并解决"No space left on device"问题？
• 如何清理 Composer 的缓存以释放磁盘空间
• Docker 报错 no space left on device 的磁盘清理
• EnvironmentError: [Errno 28] No space left on device - 完美解决方法