【Docker】dockerr build构建时遇到的 "no space left on device" 错误

你在使用 docker build或者docker-compose build 构建时遇到的 "no space left on device" 错误，通常意味着 Docker 守护进程的可用存储空间不足。这个问题在构建需要编译代码的镜像时很常见。下面是一个排查和解决的步骤指南。

🔍 排查问题根源

首先，你需要确定是宿主机的磁盘空间不足，还是 Docker 专用的存储空间已满。

1. 检查宿主机磁盘空间
   在终端中运行以下命令，查看磁盘分区的使用情况：

   df -h
   

   重点关注 Docker 默认存储目录（通常是 /var/lib/docker 所在的分区（往往是根目录 /）的使用率。如果可用空间所剩无几，就需要进行清理或扩容 。

2. 检查 Docker 内部资源占用
   有时宿主机磁盘还有空间，但 Docker 自身的资源（如构建缓存、镜像、容器）占满了它分配到的存储。可以使用以下命令查看 Docker 磁盘使用概况：

   docker system df
   

🧹 清理磁盘空间（立即缓解）

以下清理命令可以快速释放被占用的空间，请按需选择。

清理目标	命令	作用与说明
所有未使用资源	docker system prune -a -f	最直接有效。强制删除所有停止的容器、所有未被使用的网络、所有悬挂的镜像和构建缓存。注意：这可能会清除你的开发环境，使用前请谨慎。
构建缓存	docker builder prune	专门清理 BuildKit 的构建缓存，对于解决构建过程中的空间不足问题针对性很强。
** dangling 镜像**	docker image prune	删除那些没有标签的中间镜像，这些镜像会占用大量空间 。
所有已停止的容器	docker container prune	删除所有已停止的容器 。
未被使用的数据卷	docker volume prune	删除未被任何容器引用的数据卷。执行前请确认卷内无重要数据。

⚙️ 优化配置与构建流程（长期预防）

单纯清理只是临时方案，优化配置和习惯才能避免问题重复发生。

• 使用 .dockerignore 文件：在 Dockerfile 同目录下创建 .dockerignore 文件，排除构建上下文（build context）中不需要的文件（如 node_modules, .git, 日志文件、归档文件等）。这能显著减少构建时发送给 Docker 守护进程的数据量，提升构建速度并节省空间 。

• 实施多阶段构建：在你的 Dockerfile 中使用多阶段构建。这样可以在最终镜像中只包含运行所需的二进制文件和依赖，丢弃构建过程中产生的中间文件和缓存，有效减小镜像体积 。

• 配置日志轮换：默认情况下，容器的日志文件会不断增长。可以全局配置 Docker 日志驱动，限制单个日志文件的大小和数量。

  // 在 /etc/docker/daemon.json 中配置
  {
    "log-driver": "json-file",
    "log-opts": {
      "max-size": "10m",
      "max-file": "3"
    }
  }
  

  配置后需要重启 Docker 服务 。

• 调整 Docker 存储目录：如果 /var/lib/docker 所在的分区本身空间较小，可以考虑将 Docker 的默认存储目录（data-root）修改到更大的磁盘分区。这需要通过编辑 /etc/docker/daemon.json 文件并重启 Docker 服务来实现 。

💎 总结

总而言之，你可以按照以下路径来解决问题：

1. 立即执行 docker system prune -a -f 或 docker builder prune 来快速释放空间，完成当前的紧急构建。
2. 随后，通过创建或优化 .dockerignore 文件、使用多阶段构建等方式，从根源上优化你的 Docker 镜像构建流程，防止问题再次发生。