1. 概述
在使用 Docker Compose 时，有时会遇到它无法识别本地已存在的镜像，反而尝试从远程仓库（如 Docker Hub）拉取镜像的问题。这不仅会导致构建失败，还可能带来不必要的等待时间，影响开发或部署效率。
本文将分析 Docker Compose 忽略本地镜像的常见原因，并提供一系列排查和解决方案，帮助你快速定位问题并修复。
2. 问题成因分析
Docker Compose 之所以无法识别本地镜像，通常是因为镜像名称或标签不一致、环境变量配置错误，或 Docker Compose 版本兼容性问题。以下是几种常见情况：
✅ 镜像名或标签不匹配：Docker Compose 对镜像名称和标签非常敏感。例如，baeldung-server:latest 与 baeldung-server:staging 是两个完全不同的镜像。
❌ DOCKER_HOST 环境变量设置错误：如果设置了 DOCKER_HOST，Docker Compose 会连接到指定的远程主机查找镜像，而不是本地。
⚠️ docker-compose.yml 中指定的版本与实际安装的 Docker Compose 版本不兼容：不同版本的 Docker Compose 在镜像查找行为上略有差异。
3. 初步检查步骤
在深入排查前，先做一些简单检查，排除基础错误。
3.1 确认本地是否存在目标镜像
运行以下命令查看本地镜像列表：
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
baeldung-server latest 8bba7bdc05d7 3 hours ago 8.83MB
确保 docker-compose.yml 中指定的镜像和标签与输出中的一致。
3.2 检查 docker-compose.yml 文件
查看你的 docker-compose.yml 文件内容是否正确引用了镜像：
version: '3'
services:
webserver:
image: baeldung-server:latest
ports:
- "80:80"
确认 image 字段与 docker images 输出完全一致。
3.3 检查 DOCKER_HOST 环境变量
运行以下命令查看是否设置了 DOCKER_HOST：
$ echo $DOCKER_HOST
如果输出了 IP 或主机名，说明 Docker Compose 正在连接远程 Docker 守护进程。你需要清除该变量：
$ unset DOCKER_HOST
同时检查 .env 文件中是否有定义该变量并删除。
3.4 检查 Docker Compose 版本
运行以下命令查看当前 Docker Compose 版本：
$ docker-compose version
确保该版本与 docker-compose.yml 文件开头的 version 字段兼容。
4. 排查与解决方案
如果上述检查都正常，但问题依旧存在，可以尝试以下方法进一步排查。
4.1 重新构建本地镜像
如果你修改了 Dockerfile 或应用代码，Docker Compose 不会自动重新构建镜像。你需要手动清理缓存并重新构建：
# 清理构建缓存
$ docker builder prune -af
# 强制重新构建镜像
$ docker build --no-cache -t baeldung-server:latest .
然后运行：
$ docker-compose up -d
✅ Docker Compose 应该会使用最新构建的本地镜像。
4.2 使用 pull_policy 控制拉取策略
Docker Compose 提供了 pull_policy 配置项来控制镜像拉取行为。将其设置为 if_not_present 可以让 Docker Compose 优先使用本地镜像：
version: '3'
services:
webserver:
image: baeldung-server:latest
pull_policy: if_not_present
ports:
- "80:80"
pull_policy 支持的值包括：
always：总是拉取never：从不拉取missing（默认）：仅当本地不存在时拉取build：强制构建镜像
⚠️ missing 和 if_not_present 是最常用的两种策略，用于避免不必要的远程拉取。
4.3 使用本地私有 Registry
如果 Docker Compose 依然无法识别本地镜像，可以考虑将镜像推送到本地私有 Registry，再从该 Registry 拉取。
启动本地 Registry
$ docker run -d -p 5000:5000 --restart=always --name registry registry:2
标记镜像并推送到本地 Registry
$ docker tag baeldung-server:latest localhost:5000/baeldung-server:latest
修改 docker-compose.yml 文件
version: '3'
services:
webserver:
image: localhost:5000/baeldung-server:latest
ports:
- "80:80"
✅ 现在运行 docker-compose up -d 应该可以正常使用本地镜像。
4.4 使用 docker save / load 传输镜像
当你需要将镜像迁移到另一个环境中，或 Docker Compose 无法识别本地镜像时，可以使用 docker save 和 docker load 命令进行手动导入导出。
保存镜像为 tar 包
$ docker save -o baeldung-server-latest.tar baeldung-server:latest
在目标环境中加载镜像
$ docker load -i baeldung-server-latest.tar
Loaded image: baeldung-server:latest
✅ 加载后，Docker Compose 应能识别并使用该镜像。
5. 总结
本文总结了 Docker Compose 无法识别本地镜像的常见原因及解决办法，包括：
- ✅ 检查镜像名称和标签是否匹配
- ❌ 清除 DOCKER_HOST 环境变量
- ✅ 重新构建镜像并清理缓存
- ✅ 设置 pull_policy 控制拉取策略
- ✅ 使用本地私有 Registry
- ✅ 使用 save/load 手动传输镜像
通过以上方法，你可以有效解决 Docker Compose 忽略本地镜像的问题，提升开发和部署效率。