多阶段构建是解决Docker镜像层数超127上限的根本方法，通过分离构建与运行阶段、仅复制最终产物，将层数压缩至2～4层，并配合清理悬空镜像和合并RUN指令，彻底规避层数超标问题。

镜像层数超限导致构建中断，本质不是内核限制，而是 Docker 自身对镜像层深度的硬性约束（127 层上限），常见于 Windows 平台或长期未清理的构建环境。修复关键不在于“绕过内核”，而在于主动压缩层链、切断冗余依赖。

用多阶段构建重置层起点

这是最根本的解法。把构建过程拆成逻辑隔离的阶段，只把最终产物带入运行镜像，彻底丢弃中间工具链和临时文件。

• 第一阶段用完整开发镜像（如 golang:1.23 或 node:20），完成编译、测试、打包
• 第二阶段切换极简运行时（如 alpine:3.20 或 debian:slim），仅 COPY --from=builder 复制二进制或静态资源
• 整个镜像最终只有 2～4 层，天然避开 127 层红线

强制清理历史残留层

很多“层数超标”其实是旧构建缓存堆积所致，并非当前 Dockerfile 过深。

• 运行 docker builder prune -a 清空所有构建缓存（含匿名中间镜像）
• 执行 docker images -f "dangling=true" -q | xargs -r docker rmi 删除无标签悬空镜像
• 用 docker system df -v 检查 “Build Cache” 占用是否回落，确认清理生效

重构 Dockerfile 减少单次构建层数

每条 RUN、COPY、ADD 都新增一层，高频错误是过度拆分指令。

• 合并安装与清理：写成 RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
• 避免 RUN mkdir /app && COPY . /app —— COPY 会自动创建目标目录，单独 RUN mkdir 纯属多加一层
• Python 项目中，pip install 后补上 && find /usr/local -name '__pycache__' -delete && pip cache purge

紧急恢复：导出为单层镜像（仅限救急）

当必须立刻交付且无法改 Dockerfile 时可用，但会牺牲所有分层优势。

• 先构建出超层镜像：docker build -t broken:latest .
• 导出再导入：docker save broken:latest | docker load（实际执行中需配合 docker export + docker import）
• 注意：新镜像只剩 1 层，但 LABEL、ENV、CMD 等元数据全部丢失，需手动补全