用途：在调试 Docker 构建失败或缓存行为异常时使用，帮助快速定位错误类别并给出修复方向，避免因误解 COPY 上下文路径、缓存失效等问题浪费时间。
主要能力：提供构建错误调试流程（先读完整错误信息，用 --progress=plain 查看细节，再按错误类别查表修复）；包含十类诊断表：COPY/ADD 文件未找到、构建上下文过大、意外缓存失效、BuildKit 挂载错误、多阶段引用错误、基础镜像拉取失败、平台不匹配、ARG 作用域问题、构建期权限错误、Dockerfile 语法错误。另含缓存策略与 --no-cache 对比 --no-cache-filter 的决策树，以及常用调试命令。
必要用法：调试时始终使用 docker build --progress=plain .；COPY/ADD 报文件缺失时先检查 .dockerignore；重建可用 docker build --progress=plain --no-cache .；仅重建特定阶段用 docker build --no-cache-filter=<stage-name> .；只拉取新基础镜像用 docker build --pull .；查看缓存用 docker system df、docker builder prune；查看镜像层用 docker history <image>。
限制与警告：不要长期用 --no-cache 掩盖缓存问题，应找根因；不要把密钥放进 ARG 或 ENV，应使用 RUN --mount=type=secret；使用 --mount 需在 Dockerfile 首行加 # syntax=docker/dockerfile:1 并启用 BuildKit。资料未提供具体收费、平台支持范围与效果数据。