无网络环境下执行docker build失败的原因及解决方法

一、为什么无需下载新包时docker build仍需访问镜像仓库？ #

Docker默认会对FROM指令中的镜像标签（比如node:18）进行远程验证：

• 像18这类浮动标签，可能指向仓库中更新的镜像版本，Docker会自动尝试访问仓库获取该标签对应的最新manifest，确认本地镜像是否为最新版本，这个过程需要网络。
• 即使本地已经存在该镜像，只要没显式禁止拉取更新，Docker都会发起这个验证请求，这就是你报错的核心原因。

关于镜像缓存：缓存生效的前提是本地已存在完整的镜像层，且Docker判定当前构建步骤的上下文与缓存完全匹配。但如果FROM指令触发的远程验证失败，哪怕后续层有可用缓存，整个构建也会直接终止。

二、无网络机器上重建容器的方法 #

1. 提前导入所有依赖的基础镜像 #

在有网络的本地机器上，把Dockerfile中用到的基础镜像（比如node:18）打包传输到服务器：

# 本地打包镜像
docker save -o node18.tar node:18
# 通过SSH传输到服务器
scp node18.tar user@server-ip:/path/to/
# 在服务器上导入镜像
docker load -i node18.tar

2. 禁止构建时拉取镜像更新 #

执行docker build时添加--pull=false参数，强制Docker使用本地已有的镜像，不再尝试访问仓库验证：

docker build --pull=false -t your-image:latest .

如果使用Docker Compose，执行：

docker compose build --no-pull

或者在docker-compose.yml的build部分配置：

services:
  your-service:
    build:
      context: .
      pull: false

3. 消除构建过程中的网络依赖 #

如果构建中有依赖下载步骤（比如RUN npm install），需要提前在本地完成依赖准备，再通过构建上下文复制到镜像中：

• 本地执行npm install生成node_modules目录
• 在Dockerfile中用COPY指令把本地的node_modules复制到容器内，替换原有的RUN npm install指令

内容的提问来源于stack exchange，提问作者Jan Berndt