docker history --no-trunc 是查看镜像每层真实构建命令的必需参数，否则 CREATED BY 列被截断；结合 docker image inspect --format='{{.RootFS}}' 可定位各层文件系统变更。

docker history 命令怎么看镜像的每一层到底干了啥

直接看 docker history 输出，不加参数时默认只显示层级大小和创建时间，CREATED BY 列经常被截断，根本看不出 RUN 里执行的是哪条命令。这是最常踩的坑——以为看到了，其实关键信息丢了。

• 加 --no-trunc 是刚需，否则 CREATED BY 一长串被砍成 bin/sh -c #(nop) RUN ...，真实指令全没了
• 想看某一层的完整构建上下文？用 docker image inspect --format='{{.RootFS}}' 对照 docker history 的 IMAGE 列，能定位具体哪层改了什么文件系统
• 基础镜像（如 alpine:3.19）的首层通常显示为 ，这不是错误，是上游镜像没公开构建历史，别误以为本地损坏

为什么 docker history 显示的层数和 Dockerfile 行数对不上

因为 Docker 构建时会合并、跳过甚至隐式生成层级。比如多个 RUN 合并成一层（用了 BuildKit 的 SHELL 指令或 RUN --mount），或者 COPY 和紧随其后的 RUN 被优化进同一层。

• 默认使用传统 builder 时，每条指令基本对应一层；启用 BuildKit（DOCKER_BUILDKIT=1）后，分层逻辑完全不同，docker history 仍能显示，但层级含义已不是“一行 Dockerfile = 一层”
• ARG、ENV、LABEL 这类元数据指令不产生新层，但会更新当前层的配置，docker history 里看不到它们的独立记录
• 空层（size 0B）常见于 HEALTHCHECK 或 EXPOSE，它们只改镜像配置，不写文件系统

如何用 docker history 快速定位臃肿层

镜像体积大，八成是因为某一层 COPY 了不该带的东西，比如 node_modules 或 target/ 目录没清理。靠眼睛扫 SIZE 列最快。

• 加 --format "{{.ID}}\t{{.Size}}\t{{.CreatedBy}}" --no-trunc 输出制表符分隔，方便用 sort -k2 -h 按大小倒序排，一眼揪出最大的几层
• 特别注意 /bin/sh -c #(nop) COPY 后面跟了超大目录的那行——大概率就是问题源头
• 如果某层 SIZE 是 0B 但 CreatedBy 里有 RUN apt-get install，说明包管理器缓存没清，得在同一条 RUN 里连带 && apt-get clean && rm -rf /var/lib/apt/lists/*

docker history 看不到某层？可能是镜像被重打过标签或 squashed

用 docker build --squash（已弃用）或第三方工具（如 kaniko 配置 --single-snapshot）构建的镜像，所有层会被压成一层，docker history 就只剩一个 ID 和总大小。

• 确认是否被 squash：运行 docker image inspect | jq '.[0].RootFS.Layers'，如果只返回一个 hash，基本可以确定
• 这种镜像无法回溯修改点，也无法用 docker export 提取中间态文件，调试成本陡增
• CI/CD 流水线里若用了 buildx bake 并开启 cache-to，也可能导致历史被裁剪，需检查构建日志里是否有 attestations disabled 类提示

真正麻烦的不是命令不会用，而是看到 还以为网络问题或权限不对，其实镜像本身就没留历史——这点很多人卡半天才反应过来。