如何查看docker-compose build执行过程以排查构建失败问题？

一、先确认基础环境与配置合法性 #

• 核对Docker和Docker Compose版本兼容性：执行docker --version和docker-compose --version，确认两者版本匹配（参考官方兼容要求）
• 校验compose配置语法：运行docker-compose config，直接排查yml文件的格式错误、参数遗漏或逻辑冲突
• 检查目录权限：确保执行命令的用户对当前工作目录（含Dockerfile、构建上下文内的所有文件）拥有读写权限，避免因权限不足导致文件无法读取

二、拆解构建流程，缩小问题范围 #

• 单独构建单个服务：如果是多服务compose文件，先指定单个服务构建，比如docker-compose build <service-name>，定位是某个服务的问题还是全局配置问题
• 手动复现Dockerfile每一步：把Dockerfile里的命令逐条在本地或临时容器中执行——先拉取基础镜像docker pull <base-image>:<tag>，再依次运行RUN、COPY等命令，定位具体出错的步骤
• 开启构建详细输出：用docker-compose build --progress plain替代默认日志，这个参数会输出构建过程的每一行执行细节，包括命令执行的完整输出，比--log-level DEBUG更实用

三、排查构建上下文与外部依赖 #

• 检查.dockerignore规则：确认没有误排除构建必需的文件（比如依赖包、配置文件），导致COPY/ADD命令失败
• 验证外部依赖的网络连通性：如果Dockerfile里有下载操作（如apt install、pip install），在构建环境中测试网络——比如启动一个临时容器docker run --rm <base-image> curl <dependency-url>，确认依赖源可访问
• 确认基础镜像可用性：检查基础镜像的标签是否正确，尝试重新拉取docker pull <base-image>:<tag>，避免镜像损坏或拉取不完整

四、排除缓存与本地环境干扰 #

• 禁用构建缓存：执行docker-compose build --no-cache，跳过缓存直接重新构建，排除旧缓存导致的隐性问题
• 清理本地冗余资源：运行docker system prune -af清理无用镜像、容器、卷和网络，避免存储冲突或资源不足
• 在干净环境测试：复制相同的配置文件和构建上下文到另一台机器或虚拟机，执行build命令，确认问题是否是本地环境特有的

五、收集完整诊断信息 #

• 捕获全量构建日志：执行docker-compose build --progress plain 2>&1 > build-log.txt，把所有标准输出和错误输出写入日志文件，方便后续逐行分析
• 查看Docker守护进程日志：根据系统不同，查看docker daemon的底层日志——比如Ubuntu用journalctl -u docker.service，CentOS看/var/log/docker.log，排查底层的容器引擎错误

内容的提问来源于stack exchange，提问作者demented hedgehog