Docker使用buildx构建时如何强制优先使用本地已有镜像而非拉取远程

问题根因 #

Docker Buildx 默认使用 docker-container 驱动时，运行在独立的容器环境中，和本地 Docker daemon 的镜像存储完全隔离，无法直接读取本地已拉取的镜像，默认会优先尝试连接远程 registry 拉取镜像元数据，无网环境下就会触发构建失败。

可用解决方案 #

方案1：添加 --pull=never 参数（最快捷） #

直接在构建命令中添加 --pull=never 参数，强制 Buildx 跳过远程镜像检查，优先使用本地已存在的镜像缓存，同时建议添加 --load 参数将构建结果导入本地 Docker 镜像列表：

docker buildx build . --platform linux/arm64 --pull=never --load

方案2：切换 Buildx 驱动为 docker 驱动 #

docker 驱动默认和本地 Docker daemon 共享镜像存储，原生支持直接读取本地已拉取的镜像，无需额外配置：

1. 查看当前 Buildx 构建器列表

docker buildx ls

2. 创建并切换到使用 docker 驱动的构建器

docker buildx create --name local-builder --driver docker --use

3. 切换完成后直接执行原构建命令即可

docker buildx build . --platform linux/arm64

方案3：将本地镜像导入到 Buildx 构建器缓存 #

如果你必须使用 docker-container 驱动（比如需要同时构建多架构镜像），可以先把本地镜像导入到对应 Buildx 构建器的缓存中：

1. 将本地镜像导出为 tar 包

docker save ros:galactic -o ros-galactic-arm64.tar

2. 导入到指定 Buildx 构建器缓存（将命令中的 your-builder-name 替换为 docker buildx ls 中查到的实际使用的构建器名称）

docker buildx imagetools import --builder your-builder-name ros-galactic-arm64.tar

导入完成后再执行构建命令即可识别到本地镜像，无需联网拉取。

内容的提问来源于stack exchange，提问作者Marvin-wtt