--progress 是什么
--progress 控制构建日志的呈现方式。默认在交互终端里用动态刷新界面展示各步骤进度，看起来整洁但不适合留存与检索；plain 模式把每一步的完整命令与输出逐行打印，能完整落到 CI 日志或文件里，是排障时的首选。它只影响日志形式，不改变构建行为与结果。
基本信息
| 取值 | auto（默认）/ tty / plain / rawjson |
|---|---|
| 语法 | docker build --progress=plain -t 名称 . 或 docker buildx build --progress=plain . |
| auto 行为 | 有终端时用 tty 界面，无终端时退回 plain |
| plain | 逐行输出完整日志，便于检索与归档 |
| rawjson | 结构化输出，供程序解析 |
| 适用环境 | BuildKit 构建：docker 23+ 默认构建与 buildx |
典型使用场景
- CI 里保存完整构建日志，出问题可事后检索
- 构建失败时定位到具体是哪一步的哪条命令报错
- 把日志交给他人分析，需要可复制的纯文本
- 长期统计构建耗时：从日志时间戳里提取各步骤时长
- 本地排查缓存是否命中：plain 日志会明确标出缓存行
日志留存与检索
日志留存与检索
# 完整日志落盘，便于检索与对比
docker buildx build --progress=plain -t app/web:1.0 . 2>&1 | tee build.log
# 抓取报错上下文
grep -n -i -E 'error|failed' build.log | head -20
# 观察缓存命中情况
grep -n 'CACHED' build.log | head -20
# 无终端环境（CI）下默认就是 plain，显式写出来更清楚
docker buildx build --progress=plain --no-cache -t app/web:1.0 . > build-verbose.log 2>&1
tail -40 build-verbose.log模式选择
| 模式 | 呈现方式 | 适用场景 |
|---|---|---|
| auto | 有终端用动态界面，否则纯文本 | 日常交互构建 |
| tty | 动态刷新界面 | 人工观察进度 |
| plain | 逐行完整日志 | CI 归档与报错定位 |
| rawjson | 结构化事件流 | 程序化分析与统计 |
| plain 加 tee | 同时输出屏幕与文件 | 本地排障 |
| plain 加 no-cache | 完整重建日志 | 确认无缓存干扰 |
plain 日志里步骤编号与 Dockerfile 顺序对应，报错时会直接指出出错指令，把日志与文件对照阅读是最快的定位方式。
日志可能很长且包含环境变量内容，把构建日志贴到公开渠道前先检查是否带敏感信息，尤其是把构建参数透传为密钥的场景。