Docker Buildx 构建成功，docker image ls 却找不到镜像

docker buildx build -t demo-app:check . 已经结束，但 docker image ls 中没有这个标签。如果构建日志还出现 No output specified for docker-container driver，结果很可能只保存在构建器缓存中，没有导入 Docker Engine 的镜像库。-t 指定名称，本身并不保证完成导出。

这篇处理的是 docker-container 构建器未指定输出、也未启用自动加载的情况。默认 docker 驱动会自动加载镜像，不能把所有 Buildx 构建都归到这个原因。

确认使用了哪个构建器

在执行构建的同一终端查看：

docker buildx ls
docker buildx version

ls 列出构建器及其驱动，星号标记当前选择。还要检查原构建命令是否带有 --builder：显式指定的构建器优先于默认选择。若驱动为 docker-container，再核对命令中有没有 --load、--push 或 --output。

三种情况需要区分：没有指定输出时，结果通常只留在构建缓存；指定 --push 时，结果去镜像仓库；指定文件导出时，结果去相应文件或目录。后两种情况即使构建成功，本地镜像列表也不一定增加条目。

Buildx 0.14.0 及以后允许在创建构建器时设置 default-load=true，使自定义驱动默认加载结果。已经启用这项设置时，不能仅凭驱动名称就断言缺少输出；若另行指定了其他输出格式，也需要重新核对实际导出方式。

只需要本地镜像时，显式加载单个平台

保留原来的 Dockerfile、构建上下文和构建参数，加上 --load。以下示例假设构建器名为 mybuilder，Dockerfile 位于当前目录，目标是 Linux AMD64；请按实际名称和目标平台替换：

docker buildx build --builder mybuilder \
  --platform linux/amd64 \
  --load -t demo-app:check -f Dockerfile .

--load 是 --output=type=docker 的简写，会把单平台构建结果导入 Docker 镜像库。原来使用自定义 Dockerfile、构建参数或其他上下文目录时，不要在补参数的同时把这些输入换掉。重新构建可以复用仍有效的缓存，无需为了“让镜像出现”先清空缓存或加 --no-cache。

这里采用独立的 check 标签，避免直接覆盖正在部署的标签。加载完成后，用同一个 Docker 连接环境检查：

docker image inspect demo-app:check
docker image ls demo-app:check

应能读取镜像详细信息，并在列表里看到预期标签；同时检查构建日志的导出、导入阶段没有失败。若仍找不到，比较两次命令使用的 Docker context、DOCKER_HOST 和终端环境，避免构建导入了一个 Engine，却在另一个 Engine 中查找。

多平台交付使用仓库输出

如果真正需要的是 linux/amd64 与 linux/arm64 两个平台，不能把所有环境都当作支持多平台本地加载。经典镜像存储不支持多平台镜像，containerd 镜像存储支持；具体能力取决于当前 Engine 的存储配置和构建器组合。

需要交付给其他机器时，可直接推送到有写入权限的仓库。以下地址、命名空间和版本标签均为占位值，执行前确认仓库权限、可见性，以及两个平台的构建能力：

docker buildx build --builder mybuilder \
  --platform linux/amd64,linux/arm64 \
  --push -t registry.example.com/team/demo-app:build-check .

--push 会上传构建结果，不能用它来“试一下”未经授权的仓库或正式发布标签。成功后应在仓库中核对该标签及平台清单；本地 docker image ls 仍没有条目，并不表示推送失败。

镜像出现，不等于后续 FROM 一定能读取它

--load 解决的是结果进入 Docker Engine 镜像库的问题。如果下一次构建仍在 FROM demo-app:check 处报拉取失败，应单独检查后续构建器的镜像来源及仓库访问。不要把本地列表可见当作另一个构建器必然能访问该镜像的证明，也不要通过删除现有镜像来排除这种问题。

本次调整只改变输出方式，不要求修改应用代码或清理数据卷。回退时恢复原构建命令，部署继续使用此前确认的镜像标签或摘要；保留旧镜像，直到新镜像完成应用层验证。若使用了试验标签，确认无人引用后再清理对应标签，避免顺手执行全局清理。