Docker 构建失败:基础镜像未找到
快速摘要
你的 Docker 构建失败 —— Dockerfile 中 FROM 指令的基础镜像不存在或无法访问。
为什么发生
基础镜像名称拼写错误或标签在注册表中不存在
注册表是私有的且未配置认证
由于网络问题或速率限制,注册表不可达
最小示例
✗ 错误代码
FROM node:18-alpine3.99 # tag does not exist
WORKDIR /app
COPY . .
RUN npm install✓ 修复代码
FROM node:18-alpine # valid tag
WORKDIR /app
COPY . .
RUN npm install使用注册表中存在的有效基础镜像标签(node:18-alpine)允许构建继续。
如何诊断
用 docker pull 验证镜像名和标签在注册表中存在
检查注册表是否为私有且需要认证
测试到注册表的网络连接并检查速率限制
如何修复
更正 Dockerfile FROM 指令中的镜像名和标签
用 docker login 添加注册表认证或在 CI 中配置凭据
如果原始注册表不可达,使用镜像或替代注册表
如何预防
将基础镜像固定到特定标签并在构建前验证其存在
在 CI 中配置注册表认证并使用私有注册表镜像