离线构建 Docker 镜像的核心是避免构建阶段联网，提前准备依赖并本地注入：1. 用离线包预装（apt/yum/pip/npm）；2. 预置修改源的基础镜像；3. 多阶段构建分离联网编译与静态产物；4. 必要时传入代理和自签名证书。

在构建 Docker 镜像时遇到网络受限（如内网、代理不生效、镜像仓库不可达），核心思路是：避免构建阶段联网，把依赖提前准备好，再通过本地方式注入镜像。

使用离线包预装依赖（推荐）

适用于 apt/yum/pip/npm 等工具安装的软件或库。提前在可联网环境下载好离线安装包及依赖树，复制到构建机后用本地路径安装。

• Debian/Ubuntu（apt）：用 apt download 下载 deb 包及其依赖，再在 Dockerfile 中用 apt install ./xxx.deb 安装；也可用 apt-offline 工具生成完整离线包集
• CentOS/RHEL（yum/dnf）：用 yumdownloader --resolve 批量下载 rpm 包，Dockerfile 中用 rpm -ivh *.rpm 或 dnf install --disablerepo=* --enablerepo=local *.rpm
• Python（pip）：在联网环境运行 pip download -r requirements.txt --no-deps，补全依赖后统一下载，Dockerfile 中用 pip install --find-links ./packages --no-index -r requirements.txt
• Node.js（npm）：用 npm pack 打包私有模块，或 npm ci --only=production --no-audit 配合 node_modules 目录整体拷贝进镜像

构建机预置基础镜像并修改源

若无法修改 Dockerfile，但能控制构建环境，可在宿主机提前拉取并重打基础镜像，替换为内网可用源。

• 拉取原始镜像：docker pull ubuntu:22.04
• 启动临时容器，替换 apt 源为内网镜像站（如清华源镜像或公司 Nexus）：sed -i 's/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list
• 提交为新镜像：docker commit -m "use internal apt source" container_id my-ubuntu:22.04-offline
• Dockerfile 中直接 FROM my-ubuntu:22.04-offline，后续 apt 命令即可走内网源

多阶段构建 + 构建缓存复用

将联网操作全部移到“构建阶段”，最终镜像只保留静态产物，彻底规避运行时和最终镜像中的网络依赖。

• 第一阶段（builder）：使用标准镜像 + 可联网环境编译二进制（如 Go、Rust）、打包前端、构建 Java fatjar
• 第二阶段（runtime）：使用精简镜像（如 alpine 或 distroless），仅 COPY --from=builder 复制产物，不执行任何联网命令
• 关键点：确保 builder 阶段的镜像和构建逻辑可被完全缓存，下次构建时跳过联网步骤

代理配置与可信证书注入（辅助手段）

当必须联网但受限于代理或 HTTPS 证书时，需显式传递配置，而非依赖宿主机环境。

• 构建时传入代理：docker build --build-arg HTTP_PROXY=http://proxy.internal:8080 --build-arg HTTPS_PROXY=http://proxy.internal:8080 .
• Dockerfile 中声明并使用：ARG HTTP_PROXY，然后在 RUN 命令前加 export HTTP_PROXY=$HTTP_PROXY
• 若内网使用自签名证书，需在构建阶段 COPY 证书文件，并更新系统信任库（如 cp ca.crt /usr/local/share/ca-certificates/ && update-ca-certificates）