磁盘空间不足导致 RUN 失败，本质是临时空间（解压目录、包缓存、编译中间文件）无处落脚；需检查 /var/lib/docker 和 /tmp 分区使用率、优化 Dockerfile（如清理 apt/pip 缓存）、启用 BuildKit 并定期清理构建缓存。
构建时因磁盘空间不足导致 RUN 指令失败，本质不是 RUN 本身出错，而是它执行所需的临时空间（如解压目录、包缓存、编译中间文件）无处落脚。排查要从 RUN 的上下文环境切入，重点看它“在哪儿跑”“要写什么”“有没有地方写”。
盯住 RUN 执行时的临时路径
RUN 指令在构建过程中实际运行在临时容器里，其文件系统根目录通常映射到宿主机的 /var/lib/docker 或构建器的缓存工作区（如 BuildKit 的 /tmp/buildkit）。这些路径一旦所在分区满载，RUN 就会直接报 “no space left on device”。
- 运行
df -h /var/lib/docker和df -h /tmp，确认这两个挂载点是否已超 90% - 对 BuildKit 构建，加
--progress=plain参数观察日志中 RUN 步骤是否卡在 “running in container” 后无响应——这往往是磁盘写入阻塞的典型表现 - 若使用 CI/CD 平台（如 Jenkins、GitLab Runner），检查其 workspace 是否挂载在小容量分区（如仅 5GB 的 /tmp），RUN 中 pip install 或 make 编译极易撑爆它
检查 RUN 前后指令是否放大空间消耗
看似简单的 RUN，常因前序 COPY 或后续多层叠加，把空间压力推到临界点。尤其注意那些“静默吃空间”的操作：
-
COPY . /app：若项目含
node_modules、__pycache__或大模型文件，且未用.dockerignore过滤，整个目录被复制进构建上下文 → RUN 安装依赖时反复解压、缓存，空间翻倍 -
RUN apt-get install：默认保留
/var/cache/apt/archives，单次安装可能新增几百 MB；应合并为RUN apt-get update && apt-get install -y xxx && apt-get clean && rm -rf /var/lib/apt/lists/* -
RUN pip install：不加
--no-cache-dir会在/root/.cache/pip留下大量包缓存；建议显式指定--cache-dir /dev/null或挂载外部缓存卷
验证 RUN 是否触发了不可控的临时写入
某些 RUN 命令会在执行时动态生成大量临时内容，且位置不可控：
- Java 构建（
RUN mvn package）默认将 target 目录放在工作区，若 jar 包超 200MB，加上 m2 仓库缓存，极易溢出 - Go 构建（
RUN go build）若未设GOCACHE=/dev/shm，缓存默认落在/root/.cache/go-build，而/dev/shm是内存 tmpfs，更安全 - Node.js（
RUN npm ci）若node_modules已被 COPY 进来，RUN 阶段实际只是链接重装，但若没提前清理旧模块，仍会叠加占用
用 docker system df 定位真实瓶颈
别只信 df -h 显示的根分区，Docker 自身资源堆积才是常见元凶：
- 运行
docker system df -v，重点关注 “Build cache” 和 “Images” 下的 “Reclaimable” 列——若显示 “12.4GB”，说明删掉就能立刻释放 - 执行
docker builder prune（专清 BuildKit 缓存）或docker system prune -f --filter until=24h（清 24 小时内未用资源），比盲目删文件更精准 - 若频繁构建，可在 Dockerfile 开头加
ARG BUILDKIT=1并启用 BuildKit，它默认更激进地复用和清理中间层
