Dockerfile FROM引用本地镜像失败？

Question

在使用 Docker 构建镜像时，常遇到 `Dockerfile` 中 `FROM` 指令引用本地已构建镜像失败的问题。典型表现为：尽管已通过 `docker build` 成功构建并命名了镜像（如 `my-base-image:latest`），但在另一 Dockerfile 中使用 `FROM my-base-image:latest` 时仍提示 `pull access denied` 或 `manifest unknown` 错误。该问题通常源于镜像名称未正确标记、本地镜像标签缺失或构建上下文隔离导致无法识别本地镜像缓存。此外，若使用 BuildKit 后端，其默认行为可能优先尝试远程拉取而非回退本地镜像。解决方法包括确认镜像确实存在于本地（`docker images`）、确保标签准确无误，并可通过设置 `DOCKER_BUILDKIT=0` 验证是否为构建器行为差异所致。

Answer 1

一、问题背景与现象描述

在使用 Docker 构建镜像时，开发者常通过 Dockerfile 中的 FROM 指令引用一个基础镜像。当该基础镜像是本地已构建的自定义镜像（如 my-base-image:latest）时，尽管已执行 docker build -t my-base-image:latest . 并成功生成镜像，但在后续构建中仍可能遇到如下错误：

pull access denied for my-base-image, repository does not exist or may require 'docker login'
manifest unknown

此类错误误导性较强，容易让人误以为需要登录或远程仓库不存在该镜像，而实际上问题出在本地镜像识别机制上。

二、常见原因分析（由浅入深）

1. 镜像未正确打标签：构建时未使用 -t 参数指定名称和标签，导致镜像仅以随机 ID 存在。
2. 标签拼写错误：Docker 对镜像名区分大小写，My-Base-Image 与 my-base-image 被视为不同镜像。
3. 构建上下文隔离：多阶段构建或 CI/CD 环境中，不同构建任务运行在独立环境中，无法共享本地镜像缓存。
4. BuildKit 默认行为变更：启用 BuildKit 后端（DOCKER_BUILDKIT=1）时，默认优先尝试从远程注册表拉取镜像，即使本地存在同名镜像也不会自动回退。
5. 镜像存储驱动或命名空间隔离：在某些容器运行时（如 rootless 模式）下，用户命名空间可能导致镜像不可见。

三、诊断流程图

graph TD
    A[开始: 执行 docker build] --> B{提示 pull access denied?}
    B -- 是 --> C[运行 docker images]
    C --> D{是否存在目标镜像?}
    D -- 否 --> E[检查构建命令是否带 -t 标签]
    D -- 是 --> F[确认标签完全匹配]
    F --> G{使用 BuildKit? DOCKER_BUILDKIT=1}
    G -- 是 --> H[临时设置 DOCKER_BUILDKIT=0 测试]
    G -- 否 --> I[检查 daemon 是否重启过导致缓存丢失]
    H --> J[若成功，则为 BuildKit 行为差异]
    E --> K[重新构建并正确标记]
    K --> L[再次尝试 FROM 引用]
    L --> M[问题解决]
    J --> M
    I --> M
    

四、解决方案汇总

方案编号	解决方法	适用场景	命令示例
1	确保本地镜像存在且标签正确	所有环境	docker images | grep my-base-image
2	显式打标签避免遗漏	本地开发	docker tag <IMAGE_ID> my-base-image:latest
3	禁用 BuildKit 验证行为差异	调试阶段	DOCKER_BUILDKIT=0 docker build .
4	使用 --build-arg 和 ARG 配合动态基础镜像	CI/CD 多环境部署	ARG BASE_IMAGE=my-base-image:latest FROM $BASE_IMAGE
5	导入镜像到构建上下文（适用于隔离环境）	Kubernetes Build Pods	docker save my-base-image | docker load
6	启用本地私有 registry 缓存	团队协作环境	docker run -d -p 5000:5000 --name registry registry:2
7	使用 docker buildx 并配置 cache-to/cache-from	高级 CI 构建流水线	docker buildx build --cache-to type=inline ...
8	检查 Docker daemon 日志定位 pull 失败根源	疑难排查	journalctl -u docker.service
9	避免 latest 标签歧义，使用语义化版本	生产环境	my-base-image:v1.2.0
10	在 CI 中显式加载依赖镜像层	GitLab CI / GitHub Actions	- restore_cache: key: image-my-base

五、代码示例：验证 BuildKit 差异行为

以下脚本可用于对比两种构建后端的行为差异：

# Step 1: 构建基础镜像
docker build -t my-base-image:latest - < /base.txt
EOF

# Step 2: 创建引用它的 Dockerfile
cat > Dockerfile.app <<EOF
FROM my-base-image:latest
RUN cat /base.txt
CMD ["echo", "done"]
EOF

# Step 3: 使用传统构建器（应成功）
echo "[*] Testing with legacy builder..."
DOCKER_BUILDKIT=0 docker build -f Dockerfile.app .

# Step 4: 使用 BuildKit 构建器（可能失败）
echo "[*] Testing with BuildKit..."
DOCKER_BUILDKIT=1 docker build -f Dockerfile.app .