Docker 构建缓慢的根本原因往往不在镜像层本身，而在于构建上下文（Context）的传输开销。当我们执行 docker build 命令时，客户端会将命令行中指定的路径（通常是点号表示当前目录）下的所有内容递归打包，然后通过 API 发送给 Docker 守护进程。守护进程在接收到这个 tar 包之后，才基于其中的文件执行 Dockerfile 指令。如果项目根目录里混杂着 node_modules、.git、大型二进制资源或测试报告，这些无关数据就会被白白上传，既占用带宽又拖慢整个流程。
理解上下文机制首先要明确它与 Dockerfile 所处位置的关系。上下文路径决定了 COPY 和 ADD 指令能够访问的本地文件范围。很多人误以为只要在 Dockerfile 里不写某些文件的复制命令，它们就不会被传输，这是错误的。只要文件位于上下文目录树内且未被忽略，它们就一定会出现在发送给守护进程的打包流中。这也解释了为什么在包含海量小文件的项目里，即便 Dockerfile 只有三行，构建准备阶段依然要消耗几十秒。
从实现层面看，Docker 客户端调用的是归档接口，对上下文路径做逐文件遍历并生成 tar 流。在 Linux 上这一过程还会受到文件系统 inode 查询速度的影响。如果上下文包含数十万个文件，光是遍历和打包就会成为瓶颈。守护进程端解包后，再结合 build cache 判断各层是否命中。也就是说，上下文体积不仅影响网络传输，也直接拉长了解包与缓存比对的时间。
使用 .dockerignore 精确裁剪上下文
最直接有效的优化手段是编写 .dockerignore 文件，它的作用类似于 git 的 .gitignore，用来声明哪些路径不应进入构建上下文。常见误区是只忽略 node_modules，却忘了忽略本地日志、覆盖率报告、IDE 配置等。一个典型的 Node.js 项目应当把开发态产物全部排除，仅保留源码与清单文件。
下面是一份较完整的忽略示例，覆盖了大部分前端与后端项目的冗余内容：
node_modules npm-debug.log yarn-error.log .git .gitignore Dockerfile .dockerignore coverage dist *.md .vscode .idea
需要注意，.dockerignore 的匹配语法支持通配符与取反规则。例如先忽略所有文件再放开特定目录，可以写成 * 然后 !src 与 !package.json。但这种写法容易因顺序错误导致文件未被包含，调试时应通过 docker build 时的发送大小提示来确认。裁剪后，原本八百兆的上下文可以降到几兆，构建准备时间通常能从两分钟缩减到数秒。
另外一个细节是上下文路径层级。若项目仓库根目录并非服务代码根目录，应通过 -f 指定 Dockerfile 并将上下文设为子目录，例如 docker build -f apps/api/Dockerfile apps/api。这样能避免把无关的子项目也打进包里，比单纯依靠忽略规则更彻底。
多阶段构建与缓存挂载减少重复传输
即便上下文已经很小，若 Dockerfile 设计不当，仍会在构建中反复触发层重建。多阶段构建（multi-stage build）允许在一个文件中定义多个临时镜像，仅把必要产物复制到最终镜像。它虽不直接缩小上下文，却能通过分离依赖安装与编译步骤，让依赖层稳定命中缓存，从而减少因上下文变动带来的重做。
以下示例展示了前端项目的多阶段写法，构建阶段安装依赖并打包，运行阶段仅复制静态文件：
FROM node:18 AS builder WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build FROM nginx:alpine COPY --from=builder /app/dist /usr/share/nginx/html
在依赖安装这一步，由于 package.json 很少变动，只要上下文里这两个文件未改，RUN npm ci 的层就会被缓存。反之如果把 COPY . . 放在安装之前，任何源码改动都会让依赖层失效。此外，Docker 还支持 BuildKit 的挂载缓存，通过 --mount=type=cache 把包管理器的下载目录保留在宿主机，避免重复拉取。
启用 BuildKit 后，可在 Dockerfile 中这样写以加速 Node 依赖安装：
# syntax=docker/dockerfile:1 FROM node:18 WORKDIR /app COPY package.json package-lock.json ./ RUN --mount=type=cache,target=/root/.npm npm ci COPY . .
这种方式下，npm 的缓存目录不计入镜像层，却能在多次构建间复用，进一步削弱上下文变动对整体耗时的影响。对于拥有庞大依赖树的服务，这种差异在持续集成环境中尤为明显。
上下文传输与 CI 环境的协同策略
在本地开发机优化上下文后，还需考虑流水线中的行为差异。许多 CI 系统默认会先执行 git clone 完整仓库，再运行构建，此时上下文可能包含历史标签与子模块。应在 CI 配置中显式设置浅克隆或只检出当前目录，并结合上文提到的子目录上下文命令，防止把整仓送入 Docker。
另一项实用做法是利用远程构建缓存与注册表缓存。通过 docker buildx build --cache-from 指定远端镜像作为缓存源，即使本地上下文有变动，也能从已有层恢复大部分内容。此时上下文体积虽仍会影响上传，但守护进程侧的层复用率大幅提升，端到端时间显著下降。
对于超大规模单体仓库，还可评估将构建上下文改为远程 URL 或使用 docker buildx 的远程驱动，让构建直接在性能更好的机器上发生，客户端仅发送元数据。这种架构层面的调整配合前文的忽略与多阶段技巧，能够将原本难以忍受的慢构建转化为日常无感操作，真正释放容器化交付的效率优势。
DockerContext优化build_cache修改时间：2026-08-15 19:06:18