为什么 docker pull 正常，但 docker-compose up –build 却出现网络问题？

这是一个非常经典的 Docker 国内用户痛点。你问的是：

docker pull：
• 直接拉取镜像；
• Docker Engine 会使用你配置的 registry-mirrors（例如清华、中科大）；
• 因此速度快、网络稳定、基本不出错。

docker-compose up –build：
• 默认使用 BuildKit 构建引擎；
• BuildKit 不会使用 registry-mirrors（这是已知问题，见官方 issue）；
• 它构建时即使你本地已经 pull 好镜像，仍然会访问 Docker Hub 拉元数据（manifest）；
• 这个 metadata 请求不是加速镜像站能解决的 ➜ 如果网络不好就会卡住或失败。

解决办法：
方法 1：禁用 BuildKit，使用旧构建引擎

DOCKER_BUILDKIT=0 docker-compose build
docker-compose up -d

方法 2：预先构建镜像 + compose 只引用 image

如果你在中国大陆开发，推荐：永远禁用 BuildKit 构建，除非你科学上网 + 有专用加速器代理 registry。